fermilink.agents.base module

class fermilink.agents.base.ProviderAgent

Bases: ABC

Base provider contract for binary resolution and command assembly.

abstract property bin_env_key: str

Return environment key used for binary override lookup.

build_exec_command(*, provider_bin, repo_dir, prompt, sandbox_policy=DEFAULT_SANDBOX_POLICY, sandbox_mode=None, model=None, reasoning_effort=None, json_output=True)

Build provider-specific argv for one exec/chat invocation.

Parameters:

• provider_bin (str)

• repo_dir (Path)

• prompt (str)

• sandbox_policy (str)

• sandbox_mode (str | None)

• model (str | None)

• reasoning_effort (str | None)

• json_output (bool)

Return type:

list[str]

abstract property default_binary: str

Return provider CLI default binary name.

ensure_workspace_instruction_alias(repo_dir)

Ensure the provider instruction alias points to AGENTS.md.

Parameters:

repo_dir (Path)

Return type:

None

extract_assistant_text_chunk(event)

Extract one assistant text chunk and whether it is a delta chunk.

Parameters:

event (dict)

Return type:

tuple[str, bool]

normalize_process_home(env)

Normalize any provider-specific writable home paths.

Parameters:

env (dict[str, str])

Return type:

dict[str, str]

prepare_final_reply_capture_command(command, *, last_message_path, json_output)

Apply provider-specific command tweaks for final-reply file capture.

Parameters:

• command (list[str])

• last_message_path (Path)

• json_output (bool)

Return type:

list[str]

prepare_one_shot_exec_command(command)

Apply provider-specific command tweaks for one-shot exec runs.

Parameters:

command (list[str])

Return type:

list[str]

prepare_runtime_env(env, *, model=None, reasoning_effort=None)

Apply provider runtime env overrides and return cleanup paths.

Parameters:

• env (dict[str, str])

• model (str | None)

• reasoning_effort (str | None)

Return type:

tuple[dict[str, str], list[Path]]

prepare_shared_turn_command(command, *, last_message_path)

Apply provider-specific command tweaks for shared chat/loop turns.

Parameters:

• command (list[str])

• last_message_path (Path)

Return type:

list[str]

abstract property provider: str

Return canonical provider id (for example codex).

provider_id()

Return type:

str

remove_workspace_instruction_alias_symlink(repo_dir)

Remove the provider alias symlink while leaving real files untouched.

Parameters:

repo_dir (Path)

Return type:

None

render_stream_event(event, *, use_color=True)

Convert one provider stream event to human-readable terminal text.

Parameters:

• event (dict)

• use_color (bool)

Return type:

str | None

resolve_binary(*, provider_bin_override=None)

Resolve executable name/path for this provider.

Parameters:

provider_bin_override (str | None)

Return type:

str

resolve_binary_override(raw_override=None)

Resolve an optional compatibility override for this provider binary.

Parameters:

raw_override (str | None)

Return type:

str | None

sanitize_process_env(env)

Apply provider-specific subprocess environment sanitation.

Parameters:

env (dict[str, str])

Return type:

dict[str, str]

service_env_overrides(*, cwd)

Return provider-specific service env vars derived from the parent env.

Parameters:

cwd (Path)

Return type:

dict[str, str]

supports_auto_compile_metadata_generation()

Return whether this provider supports auto-compile metadata generation.

Return type:

bool

supports_direct_terminal_stream()

Return whether direct terminal passthrough is preferred for this provider.

Return type:

bool

uses_json_output_for_second_guess()

Return whether second-guess subprocesses should request JSON output.

Return type:

bool

uses_json_stream()

Return whether shared CLI execution should request stream-json output.

Return type:

bool

workspace_instruction_alias_name()

Return provider-native instruction alias filename, if any.

Return type:

str | None

fermilink.agents.base.insert_option_before_prompt(command, *option_tokens)

Insert option tokens before the final prompt argument.

Parameters:

• command (list[str])

• option_tokens (str)

Return type:

list[str]