fermilink.agents package

class fermilink.agents.AgentRegistry[source]

Bases: object

Lookup registry for provider adapters.

__init__(agents)[source]
Parameters:

agents (Iterable[ProviderAgent])

Return type:

None

all()[source]
Return type:

tuple[ProviderAgent, …]

get(provider)[source]
Parameters:

provider (str)

Return type:

ProviderAgent

provider_bin_default_map()[source]
Return type:

dict[str, str]

provider_bin_env_map()[source]
Return type:

dict[str, str]

class fermilink.agents.ClaudeAgent[source]

Bases: ProviderAgent

Claude provider adapter with provider-native CLI translation.

REASONING_MAP = {'xhigh': 'high'}
SANDBOX_PERMISSION_MODE = {'read-only': 'plan', 'workspace-write': 'acceptEdits'}
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)[source]

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]

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]

property provider: str

Return canonical provider id (for example codex).

provider_id()
Return type:

str

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()[source]

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

Return type:

bool

workspace_instruction_alias_name()[source]

Return provider-native instruction alias filename, if any.

Return type:

str | None

class fermilink.agents.CodexAgent[source]

Bases: ProviderAgent

Codex provider adapter with parity to the legacy command builder.

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)[source]

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]

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)[source]

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)[source]

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)[source]

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)[source]

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

Parameters:

  • command (list[str])

  • last_message_path (Path)

Return type:

list[str]

property provider: str

Return canonical provider id (for example codex).

provider_id()
Return type:

str

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)[source]

Resolve executable name/path for this provider.

Parameters:

provider_bin_override (str | None)

Return type:

str

resolve_binary_override(raw_override=None)[source]

Resolve an optional compatibility override for this provider binary.

Parameters:

raw_override (str | None)

Return type:

str | None

sanitize_process_env(env)[source]

Apply provider-specific subprocess environment sanitation.

Parameters:

env (dict[str, str])

Return type:

dict[str, str]

service_env_overrides(*, cwd)[source]

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

Parameters:

cwd (Path)

Return type:

dict[str, str]

supports_auto_compile_metadata_generation()[source]

Return whether this provider supports auto-compile metadata generation.

Return type:

bool

supports_direct_terminal_stream()[source]

Return whether direct terminal passthrough is preferred for this provider.

Return type:

bool

uses_json_output_for_second_guess()[source]

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

class fermilink.agents.DeepseekAgent[source]

Bases: ProviderAgent

DeepSeek provider adapter with provider-native CLI translation.

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)[source]

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]

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]

property provider: str

Return canonical provider id (for example codex).

provider_id()
Return type:

str

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()[source]

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

class fermilink.agents.GeminiAgent[source]

Bases: ProviderAgent

Gemini provider adapter with provider-native CLI translation.

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)[source]

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]

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)[source]

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]

property provider: str

Return canonical provider id (for example codex).

provider_id()
Return type:

str

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()[source]

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

Return type:

bool

workspace_instruction_alias_name()[source]

Return provider-native instruction alias filename, if any.

Return type:

str | None

class fermilink.agents.ProviderAgent[source]

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)[source]

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)[source]

Ensure the provider instruction alias points to AGENTS.md.

Parameters:

repo_dir (Path)

Return type:

None

extract_assistant_text_chunk(event)[source]

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

Parameters:

event (dict)

Return type:

tuple[str, bool]

normalize_process_home(env)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]
Return type:

str

Remove the provider alias symlink while leaving real files untouched.

Parameters:

repo_dir (Path)

Return type:

None

render_stream_event(event, *, use_color=True)[source]

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)[source]

Resolve executable name/path for this provider.

Parameters:

provider_bin_override (str | None)

Return type:

str

resolve_binary_override(raw_override=None)[source]

Resolve an optional compatibility override for this provider binary.

Parameters:

raw_override (str | None)

Return type:

str | None

sanitize_process_env(env)[source]

Apply provider-specific subprocess environment sanitation.

Parameters:

env (dict[str, str])

Return type:

dict[str, str]

service_env_overrides(*, cwd)[source]

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

Parameters:

cwd (Path)

Return type:

dict[str, str]

supports_auto_compile_metadata_generation()[source]

Return whether this provider supports auto-compile metadata generation.

Return type:

bool

supports_direct_terminal_stream()[source]

Return whether direct terminal passthrough is preferred for this provider.

Return type:

bool

uses_json_output_for_second_guess()[source]

Return whether second-guess subprocesses should request JSON output.

Return type:

bool

uses_json_stream()[source]

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

Return type:

bool

workspace_instruction_alias_name()[source]

Return provider-native instruction alias filename, if any.

Return type:

str | None

fermilink.agents.get_default_agent_registry()[source]
Return type:

AgentRegistry

fermilink.agents.get_provider_agent(provider)[source]
Parameters:

provider (str)

Return type:

ProviderAgent

Submodules