@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/gateway/mcp/runtime-tool-definitions.ts

@@ -0,0 +1,546 @@
+import type { McpToolDefinition } from '../../../cli/mcp/tools';
+import { CONTROLLER_CONTEXT_IMPACT_DOMAINS } from '../../../cli/controller/context-pack';
+
+function definition(name: string, description: string, properties: Record<string, unknown>, required: string[] = [], readOnly = true): McpToolDefinition {
+  return {
+    name,
+    description,
+    inputSchema: { type: 'object', properties, ...(required.length ? { required } : {}), additionalProperties: false },
+    annotations: { readOnlyHint: readOnly, openWorldHint: false, destructiveHint: false },
+  };
+}
+const repoId = { type: 'string', description: 'Stable repository id.' };
+export const runtimeToolDefinitions: McpToolDefinition[] = [
+  definition('rh_status', 'Preferred ChatGPT facade: bounded controller status, capability readiness, and self-healing diagnose/repair.', {
+    repo_id: repoId,
+    operation: { type: 'string', enum: ['list', 'get', 'repair'], description: 'Defaults to get.' },
+    detail_level: { type: 'string', enum: ['summary', 'detail'], description: 'Defaults to summary.' },
+    repair_operation: { type: 'string', enum: ['diagnose', 'repair', 'verify', 'handoff'] },
+    dry_run: { type: 'boolean', description: 'Defaults to true for repair/diagnose.' },
+    approval_confirmed: { type: 'boolean' },
+    chatgpt_pull_failed: { type: 'boolean' },
+    destructive: { type: 'boolean' },
+  }),
+  definition('rh_inbox', 'Preferred ChatGPT facade: pending handoff decisions only (not logs).', {
+    repo_id: repoId,
+    operation: { type: 'string', enum: ['list', 'get', 'ack', 'accept', 'resolve', 'dismiss', 'create'], description: 'Defaults to list (pending).' },
+    handoff_id: { type: 'string' },
+    work_id: { type: 'string' },
+    title: { type: 'string' },
+    reason: { type: 'string' },
+    summary: { type: 'string' },
+    recommended_decision: { type: 'string' },
+    recommended_prompt: { type: 'string' },
+    decision: { type: 'string', description: 'Recorded on resolve/dismiss.' },
+    resolver: { type: 'string', description: 'Who resolved or dismissed the handoff.' },
+    detail_level: { type: 'string', enum: ['summary', 'detail'] },
+    limit: { type: 'number' },
+  }),
+  definition('rh_context', 'Preferred ChatGPT facade and default repository code-discovery/read path. Start broad once to combine heuristic lexical discovery, current raw source, and optional CodeGraph structural evidence with few round trips. Natural-language lexical terms are discovery hints: do not require every guessed term to match and do not repeat the same broad search merely because a heuristic term missed. After credible files or symbols are found, derive follow-up paths/symbols from the returned source and prefer known_paths, compiler semantic_navigation/@tsnav for TypeScript, or structural relationships before another broad lexical pass. Call rh_context repeatedly only when that progressive expansion can materially improve correctness; follow-ups reuse session-scoped evidence when source identity is unchanged. Shell rg/grep/sed/cat loops are fallback-only when this Context Plane cannot supply the needed evidence.', {
+    repo_id: repoId,
+    checkout_id: { type: 'string', description: 'Optional checkout identity for repositories with multiple worktrees.' },
+    operation: { type: 'string', enum: ['list', 'get', 'search'], description: 'Defaults to get. Use search as the default code-location path when an exact file is unknown.' },
+    query: { type: 'string', description: 'Code/content intent for operation=search. For operation=list, a natural-language capability intent such as "configure Xcode provisioning" returns ranked read-only capability candidates while execution remains on the capability\'s typed executor. Frozen-schema clients may append @tsnav or @swiftnav references|definition|implementations <repo-path>:<line>:<column> for compiler/LSP-backed semantic navigation.' },
+    known_paths: { type: 'array', items: { type: 'string' }, description: 'Optional exact paths or globs that should receive highest retrieval priority.' },
+    include_globs: { type: 'array', items: { type: 'string' } },
+    exclude_globs: { type: 'array', items: { type: 'string' } },
+    retrieval_mode: { type: 'string', enum: ['implementation', 'plan', 'debug', 'review'], description: 'Defaults to implementation. Implementation returns current raw impact evidence for ChatGPT to judge; plan/debug/review intentionally widen evidence.' },
+    impact_domains: { type: 'array', items: { type: 'string', enum: [...CONTROLLER_CONTEXT_IMPACT_DOMAINS] }, description: 'Optional GPT-selected cross-cutting evidence dimensions. Forge expands these mechanically in the same retrieval call; it never treats them as proof of semantic completeness.' },
+    structural_context: { type: 'string', enum: ['off', 'auto', 'required'], description: 'Optional override. Defaults to auto for implementation/review and required for plan/debug.' },
+    semantic_navigation: {
+      type: 'array',
+      maxItems: 8,
+      description: 'Optional bounded semantic navigation through the provider registry. TypeScript uses the in-process Language Service; Swift uses SourceKit-LSP only with existing build settings; registered generic LSP providers currently cover Rust, Go, Python, and C/C++ when their language-server executable and project root markers already exist. Providers start lazily only for explicit semantic requests; Forge never installs a server, triggers a build, or treats language-server output as source authority.',
+      items: {
+        type: 'object',
+        required: ['navigation', 'path', 'line', 'column'],
+        additionalProperties: false,
+        properties: {
+          navigation: { type: 'string', enum: ['definition', 'references', 'implementations'] },
+          path: { type: 'string' },
+          line: { type: 'number' },
+          column: { type: 'number' },
+          tsconfig_path: { type: 'string' },
+          language: { type: 'string', description: 'Optional provider-routing hint. File extension remains the default routing signal.' },
+        },
+      },
+    },
+    max_files: { type: 'number' },
+    max_snippets: { type: 'number' },
+    requested_check_ids: { type: 'array', items: { type: 'string' }, description: 'Optional execution preflight. When supplied, returns registered checks plus dependency and resource-compatible scheduling readiness; omit for source-only retrieval.' },
+    capability_id: { type: 'string', description: 'Optional capability identity. For plugin.<pluginId>.<actionId>, returns the exact typed action schema/policy for plugin_action_execute.' },
+    work_id: { type: 'string' },
+    detail_level: { type: 'string', enum: ['summary', 'detail', 'raw'], description: 'Defaults to summary; raw is still bounded.' },
+  }),
+  definition('rh_work', 'Preferred ChatGPT facade for bounded execution, optional Requirement authority, optional planning, controller ownership, and external SuperController launch. Requirement and Plan are not universal prerequisites: start explicit bounded work directly when safe, establish Requirement authority only when durable goal identity is useful, and use Plan only for real decomposition, dependency ordering, or replanning.', {
+    repo_id: repoId,
+    operation: { type: 'string', enum: ['start', 'continue', 'verify', 'repair', 'finalize', 'stop', 'delegate', 'controller_claim', 'controller_release', 'controller_disposition', 'controller_get_owner', 'launcher_start', 'requirement_create', 'plan_create', 'plan_get', 'plan_list', 'plan_approve', 'plan_accept_step', 'plan_supersede', 'schedule_create', 'schedule_list', 'schedule_get', 'schedule_pause', 'schedule_resume', 'schedule_delete', 'schedule_trigger'], description: 'Defaults to start. controller_disposition records ChatGPT\'s explicit end-of-round continue/wait decision; Forge never infers the semantic next step. requirement_create establishes optional durable Requirement authority only and never implies plan_create. Plan-bound starts require plan_id and plan_step_id, but Plan is a late semantic commitment for real decomposition/replanning rather than a universal complex-task wrapper. plan_accept_step records explicit Controller semantic acceptance after machine delivery leaves a step validating. schedule_* manages Work-bound continuation, bounded browser observation, and explicit standalone browser keepalive.' },
+    objective: { type: 'string' },
+    capability_id: { type: 'string', description: 'Legacy-readable compatibility input. operation=repair with capability_id=schedule.delete:<scheduleId> maps to canonical schedule_delete; controller.disposition:<disposition>:<relayScopeId> maps to canonical controller_disposition for frozen clients.' },
+    work_id: { type: 'string' },
+    related_work_id: { type: 'string', description: 'Optional explicit existing Work ownership target for continue/extend semantics. Unrelated active Work is never inferred as a semantic target.' },
+    work_relation: { type: 'string', enum: ['continue', 'extend', 'parallel', 'new_goal'], description: 'Optional semantic relation to an explicitly related Work. This field never selects Direct/Process/Durable execution depth; checkout conflicts are resolved by placement.' },
+    related_plan_id: { type: 'string', description: 'Existing active Plan selected when resolving another slice under the same Requirement.' },
+    plan_relation: { type: 'string', enum: ['extend', 'parallel'], description: 'Relationship to another active Plan under the same Requirement. Omit to receive candidates first. parallel explicitly permits a distinct Plan slice; extend reuses the existing Plan authority and requires replanning/supersession instead of creating another draft.' },
+    requested_by: { type: 'string', enum: ['chatgpt', 'user', 'system', 'scheduler'], description: 'Origin of the request. Scheduler-origin starts are continuation-only and cannot create new durable Work.' },
+    requirement_id: { type: 'string', description: 'Optional stable Requirement authority used to find related active Work before creation; ordinary Work may start without Requirement or Plan authority.' },
+    requirement_title: { type: 'string', description: 'Human-readable Requirement title for requirement_create.' },
+    requirement_outcome: { type: 'string', description: 'Durable outcome statement for requirement_create.' },
+    requirement_acceptance_criteria: { type: 'array', items: { type: 'string' }, description: 'Bounded semantic acceptance criteria for requirement_create.' },
+    requirement_delivery_references: { type: 'array', items: { type: 'string' }, description: 'Optional durable delivery/reference identifiers for requirement_create.' },
+    requirement_legacy_aliases: { type: 'array', items: { type: 'string' }, description: 'Optional migration aliases for requirement_create; not a second identity authority.' },
+    handoff_id: { type: 'string', description: 'Optional existing HandoffItem used to resume controller context. Required for controller_disposition=wait_for_user.' },
+    disposition: { type: 'string', enum: ['continue_immediately', 'wait', 'wait_for_user', 'goal_complete'], description: 'Explicit ChatGPT end-of-round semantic decision. continue_immediately is consumed only after the current controller lease closes.' },
+    relay_scope_id: { type: 'string', description: 'Stable Requirement/Goal relay identity. Requirement-bound Work uses requirement:<id>; otherwise reuse the exact returned goal scope across Works.' },
+    state_fingerprint: { type: 'string', description: 'Optional controller-observed semantic-state fingerprint. When omitted, Forge derives a mechanical fingerprint from current Requirement/Work/Handoff state.' },
+    max_rounds: { type: 'number', description: 'Mechanical immediate-relay round budget; defaults to 8 and cannot be loosened within an existing relay scope.' },
+    max_repeated_state: { type: 'number', description: 'Mechanical repeated-state fence; defaults to 2 repeated observations and cannot be loosened within an existing relay scope.' },
+    controller_id: { type: 'string', description: 'Stable external SuperController identity for controller_claim/release.' },
+    controller_type: { type: 'string', enum: ['chatgpt', 'codex', 'grok', 'claude', 'human'], description: 'Controller kind for claims and launcher_start.' },
+    session_id: { type: 'string', description: 'Controller-owned session identity used for an exclusive Work lease.' },
+    lease_ms: { type: 'number', description: 'Authenticated Controller ownership lease duration, bounded to one hour. Legacy launcher callers may still use this as a launch-reservation TTL.' },
+    launch_reservation_ms: { type: 'number', description: 'Short duplicate-spawn reservation TTL for launcher_start or schedule_create; does not grant Work ownership.' },
+    executable: { type: 'string', description: 'External controller executable for launcher_start. This is owned by the Launcher, not the Kernel.' },
+    launch_args: { type: 'array', items: { type: 'string' }, description: 'Provider-specific arguments for launcher_start.' },
+    browser_session_id: { type: 'string', description: 'Saved Forge ChatGPT browser session to continue when controller_type=chatgpt.' },
+    conversation_url: { type: 'string', description: 'Explicit https://chatgpt.com conversation URL used when no saved Forge browser session exists.' },
+    continuation_prompt: { type: 'string', description: 'Bounded Work continuation instruction.' },
+    schedule_id: { type: 'string', description: 'Schedule identity for schedule_get/pause/resume/delete/trigger.' },
+    schedule_name: { type: 'string', description: 'Human-readable schedule name.' },
+    schedule_request_id: { type: 'string', description: 'Stable idempotency key for schedule_create.' },
+    schedule_mode: { type: 'string', enum: ['continuation', 'browser_watch', 'browser_keepalive'], description: 'Defaults to continuation when work_id is present. browser_keepalive may run without a durable Work; continuation and browser_watch remain Work-bound.' },
+    probe_url: { type: 'string', description: 'Allowed URL to navigate or refresh for browser_watch/browser_keepalive.' },
+    probe_browser_session_id: { type: 'string', description: 'Existing Forge browser session used as the external observation target.' },
+    probe_selector: { type: 'string', description: 'Optional selector limiting text extraction for browser_watch.' },
+    probe_max_chars: { type: 'number', description: 'Bounded extracted text size for browser_watch.' },
+    probe_timeout_ms: { type: 'number', description: 'Bounded browser probe timeout.' },
+    include_terms: { type: 'array', items: { type: 'string' }, description: 'Optional case-insensitive terms; only matching normalized lines contribute to the observation fingerprint.' },
+    ignore_patterns: { type: 'array', items: { type: 'string' }, description: 'Optional regex patterns stripped before fingerprinting volatile text such as relative timestamps.' },
+    login_url_terms: { type: 'array', items: { type: 'string' }, description: 'Configured URL markers that classify the browser observation as authentication-required.' },
+    login_text_terms: { type: 'array', items: { type: 'string' }, description: 'Configured page-text markers that classify the browser observation as authentication-required.' },
+    wake_on_first_observation: { type: 'boolean', description: 'Defaults false so the first browser_watch occurrence records a silent baseline.' },
+    wake_on_auth_required: { type: 'boolean', description: 'Defaults true for browser schedules. Standalone browser_keepalive dispatches the configured ChatGPT auth-required prompt without creating a synthetic Work.' },
+    auth_required_prompt: { type: 'string', description: 'Optional ChatGPT continuation instruction when the probe detects a login marker.' },
+    trigger_type: { type: 'string', enum: ['interval', 'cron', 'calendar', 'condition', 'repository-event', 'dependency-checkpoint', 'manual'] },
+    every_minutes: { type: 'number', description: 'Interval trigger cadence in minutes.' },
+    cron_expression: { type: 'string' },
+    schedule_timezone: { type: 'string' },
+    catch_up_minutes: { type: 'number' },
+    calendar_at: { type: 'string' },
+    condition: { type: 'object' },
+    event_name: { type: 'string' },
+    event_id: { type: 'string' },
+    event_data: { type: 'object' },
+    dependency_job_ids: { type: 'array', items: { type: 'string' } },
+    max_failures: { type: 'number' },
+    cooldown_minutes: { type: 'number' },
+    daily_budget_minutes: { type: 'number' },
+    shadow_mode: { type: 'boolean', description: 'Defaults to true. Set false only after the continuation path has been validated.' },
+    backoff_base_minutes: { type: 'number' },
+    backoff_max_minutes: { type: 'number' },
+    include_occurrences: { type: 'boolean' },
+    plan_id: { type: 'string' },
+    plan_step_id: { type: 'string', description: 'PlanContract step identity. Used to bind a complex Goal Workloop start and to accept a validating step.' },
+    acceptance_rationale: { type: 'string', description: 'Controller rationale for plan_accept_step after reviewing the completed Work evidence against the Plan step acceptance criteria.' },
+    scope_key: { type: 'string', description: 'Stable normalized scope identity used to prevent overlapping active plans.' },
+    source_revision: { type: 'string', description: 'Repository revision observed during read-only planning preflight.' },
+    plan_steps: { type: 'array', items: { type: 'object' }, description: 'Bounded plan steps with id, objective, dependencies, authoritative_files, allowed_paths, forbidden_paths, check_ids, and acceptance_criteria.' },
+    non_goals: { type: 'array', items: { type: 'string' } },
+    assumptions: { type: 'array', items: { type: 'string' } },
+    resolved_decisions: { type: 'array', items: { type: 'string' } },
+    stop_conditions: { type: 'array', items: { type: 'string' } },
+    replan_conditions: { type: 'array', items: { type: 'string' } },
+    integration_strategy: { type: 'string' },
+    superseded_by: { type: 'string' },
+    expected_files: { type: 'number' },
+    expected_changed_lines: { type: 'number' },
+    mode: { type: 'string', enum: ['scale'], description: 'Explicit Scale coordination mode for start. Scale requires a bound approved PlanContract step and uses existing Work/Process/resource-claim authorities; it does not create an agent-swarm lifecycle.' },
+    work_kind: { type: 'string', enum: ['repository_change', 'completed_no_change', 'investigation', 'local_effect', 'remote_effect', 'reconciliation'], description: 'Explicit technical Work evidence shape for operation=start. local_effect/remote_effect represent effect-only execution and do not require a repository diff; completed_no_change/investigation/reconciliation likewise do not imply a source mutation. None of these imply semantic completion; ChatGPT must still explicitly finalize after reviewing evidence.' },
+    scope_clear: { type: 'boolean' },
+    requires_investigation: { type: 'boolean' },
+    requires_long_running_checks: { type: 'boolean' },
+    requires_parallelism: { type: 'boolean' },
+    needs_dependencies: { type: 'boolean' },
+    requires_recovery: { type: 'boolean' },
+    requires_worker: { type: 'boolean', description: 'Opt-in only. Set true only when the user explicitly requests Codex/Claude or another agent worker; never infer it from task complexity.' },
+    requires_external_effect: { type: 'boolean' },
+    requires_approval: { type: 'boolean' },
+    requires_user_approval: { type: 'boolean' },
+    destructive: { type: 'boolean' },
+    remote_write: { type: 'boolean' },
+    secret_access: { type: 'boolean' },
+    approval_confirmed: { type: 'boolean' },
+    dry_run: { type: 'boolean', description: 'Defaults to true for repair.' },
+    check_ids: { type: 'array', items: { type: 'string' }, description: 'Requested checks. Before launching multiple checks concurrently, call rh_context with requested_check_ids to read resource-compatible checkScheduling waves; do not overlap checks from different waves.' },
+    check_id: { type: 'string' },
+    acceptance_criteria: { type: 'array', items: { type: 'string' } },
+    allowed_paths: { type: 'array', items: { type: 'string' } },
+    initial_likely_paths: { type: 'array', items: { type: 'string' }, description: 'Non-authoritative first-pass discovery candidates. May expand after investigation; allowed_paths remains a policy fence only.' },
+    additional_likely_paths: { type: 'array', items: { type: 'string' }, description: 'Non-authoritative candidates discovered after Work start. Valid for continue; does not widen allowed_paths.' },
+    inspected_paths: { type: 'array', items: { type: 'string' }, description: 'Paths actually inspected during progressive discovery. Valid for continue; does not widen allowed_paths.' },
+    acceptance_failure_decision: { type: 'string', enum: ['repair', 'rescope'], description: 'Explicit Controller decision for operation=continue after a deterministic valid_fail. Bypasses acceptance-review handoff only for this bounded repair/re-scope decision; never inferred from free text.' },
+    forbidden_paths: { type: 'array', items: { type: 'string' } },
+    constraints: { type: 'object' },
+    repair_operation: { type: 'string', enum: ['diagnose', 'repair', 'verify', 'handoff'] },
+    target: { type: 'string', enum: ['codex', 'grok', 'claude'], description: 'Explicit small-brain delegate target for operation=delegate. Delegation is never the default execution path.' },
+    available: { type: 'boolean', description: 'Whether the delegate target is currently available.' },
+    codex_available: { type: 'boolean' },
+    simulate_check: { type: 'boolean', description: 'Test hook: skip real check execution and use infrastructure_failed/check_failed flags.' },
+    infrastructure_failed: { type: 'boolean' },
+    check_failed: { type: 'boolean' },
+    authorize_destructive_cleanup: { type: 'boolean' },
+    commit: { type: 'boolean', description: 'Finalize override. Defaults to true only when the Work owns uncommitted changes.' },
+    merge: { type: 'boolean', description: 'Finalize override. Defaults to true for managed Work delivery.' },
+    cleanup: { type: 'boolean', description: 'Finalize/stop override. Defaults to true so managed worktrees close automatically.' },
+    target_branch: { type: 'string', description: 'Delivery branch; defaults to the repository default branch.' },
+    delete_branch: { type: 'boolean', description: 'Defaults to true after target-branch containment is proven.' },
+    no_ff: { type: 'boolean' },
+    completion_outcome: { type: 'string', enum: ['completed_changed', 'completed_no_change', 'completed_local', 'completed_remote'], description: 'Explicit completion semantics. completed_local is for controller-local effect Work finalized from durable result evidence; completed_remote remains bound to a durable remote plugin receipt.' },
+    no_change_evidence: { type: 'string', description: 'Optional explicit proof for a no-change completion; otherwise the lifecycle coordinator derives proof only for an unchanged validated HEAD.' },
+    reconcile_historical_delivery: { type: 'boolean', description: 'Explicitly request reviewed reconciliation for a historically delivered repository Work whose original receipt is missing. Managed Work is eligible only after merge, branch cleanup, and worktree cleanup are durably complete.' },
+    reconcile_target_revision: { type: 'string', description: 'Exact already-integrated commit accepted by the reviewer.' },
+    reconcile_compared_paths: { type: 'array', items: { type: 'string' }, description: 'Complete exact path set changed from the Work base revision to reconcile_target_revision.' },
+    reconcile_rationale: { type: 'string', description: 'Bounded reviewer rationale for accepting the historical delivery.' },
+    reconcile_cleanup_proof: { type: 'string', description: 'Concrete proof that no owned cleanup remains or that cleanup is complete.' },
+    detail_level: { type: 'string', enum: ['summary', 'detail'] },
+    reason: { type: 'string', description: 'Bounded reason for a work stop or repair record.' },
+  }, [], false),
+  definition('work_get', 'Resume one Work by work_id or request_id. Repository scope is always enforced.', {
+    repo_id: repoId,
+    work_id: { type: 'string' },
+    request_id: { type: 'string' },
+    include_events: { type: 'boolean' },
+    wait: { type: 'boolean', description: 'When true, wait for terminal status before returning digest.' },
+    wait_ms: { type: 'number' },
+  }),
+  definition('work_list', 'List recent resumable Work for one repository.', {
+    repo_id: repoId,
+    limit: { type: 'number' },
+  }),
+  definition('work_cancel', 'Cancel one queued or running Work by work_id or request_id.', {
+    repo_id: repoId,
+    work_id: { type: 'string' },
+    request_id: { type: 'string' },
+    reason: { type: 'string' },
+  }, [], false),
+  definition('work_wait', 'Wait for one Work/ExecutionJob/managed process to reach a terminal status and return a bounded operation digest.', {
+    repo_id: repoId,
+    work_id: { type: 'string' },
+    request_id: { type: 'string' },
+    wait_ms: { type: 'number', description: 'Max wait in ms. Default 15000, max 120000.' },
+  }),
+  definition('git_diff_paths', 'Return a bounded Git diff and status for explicit repository-relative paths only.', {
+    repo_id: repoId,
+    paths: { type: 'array', items: { type: 'string' } },
+    staged: { type: 'boolean' },
+    max_bytes: { type: 'number' },
+  }, ['paths']),
+  definition('git_stage_paths', 'Stage explicit repository-relative paths only using git add --all -- <paths>.', {
+    repo_id: repoId,
+    paths: { type: 'array', items: { type: 'string' } },
+  }, ['paths'], false),
+  definition('git_commit_paths', 'Stage and commit explicit repository-relative paths only, leaving unrelated staged changes untouched.', {
+    repo_id: repoId,
+    paths: { type: 'array', items: { type: 'string' } },
+    message: { type: 'string' },
+  }, ['paths', 'message'], false),
+  definition('prepare_transfer_artifacts', 'Refresh rebuildable session continuation plus a selected-path patch transfer artifact when recovery context is needed.', {
+    repo_id: repoId,
+    reason: { type: 'string' },
+  }, [], false),
+  definition('get_job', 'Read one durable Execution Job. Summary is the default; opt in to full state only when needed.', {
+    job_id: { type: 'string' },
+    repo_id: repoId,
+    include_events: { type: 'boolean' },
+    detail_level: { type: 'string', enum: ['summary', 'full'] },
+    wait: { type: 'boolean', description: 'When true, wait for terminal status before returning digest.' },
+    wait_ms: { type: 'number' },
+  }, ['job_id']),
+  definition('get_artifact', 'Read one bounded Evidence Plane artifact by id. Large content remains bounded.', { artifact_id: { type: 'string' }, repo_id: repoId, max_bytes: { type: 'number' } }, ['artifact_id', 'repo_id']),
+  definition('repository_change_verify', 'Composite: verify checkout/SHA, apply bounded patch, run checks, return first failure inline without get_job/get_artifact follow-ups.', {
+    repo_id: repoId,
+    expected_branch: { type: 'string' },
+    expected_head: { type: 'string' },
+    expected_file_shas: { type: 'object', additionalProperties: { type: 'string' } },
+    patch: { type: 'string', description: 'Unified diff applied with git apply.' },
+    allowed_paths: { type: 'array', items: { type: 'string' } },
+    checks: { type: 'array', items: { type: 'string' } },
+    check_timeout_ms: { type: 'number' },
+  }, [], false),
+  definition('list_jobs', 'List durable Execution Jobs for one repository. Summary is the default.', {
+    repo_id: repoId,
+    limit: { type: 'number' },
+    detail_level: { type: 'string', enum: ['summary', 'full'] },
+  }),
+  definition('cancel_job', 'Cancel one queued or running durable Execution Job.', { job_id: { type: 'string' }, repo_id: repoId, reason: { type: 'string' } }, ['job_id'], false),
+  definition('controller_ready', 'Return one binary Runtime readiness decision with bounded diagnostic evidence.', {
+    repo_id: repoId,
+  }),
+  definition('repository_runtime_snapshot', 'Read the materialized runtime projection without scanning historical state.', { repo_id: repoId }),
+  definition('schedule_dedupe_report', 'Read-only report that groups duplicate schedules by semantic trigger/action identity.', {
+    repo_id: repoId,
+  }, ['repo_id']),
+  definition('schedule_dedupe_apply', 'Pause duplicate schedules after explicit authorization, keeping one canonical enabled schedule per semantic identity.', {
+    repo_id: repoId,
+    dry_run: { type: 'boolean', description: 'When true, only returns the proposed changes.' },
+    confirm_authorization: { type: 'boolean', description: 'Must be true unless dry_run is true.' },
+  }, ['repo_id']),
+  definition('runtime_performance_diagnostics', 'Diagnose forge host performance, orphan workers, Local Controller presence, and cleanup candidates.', {
+    repo_id: repoId,
+    include_processes: { type: 'boolean', description: 'Include bounded forge related process samples. Defaults to true.' },
+    include_temp_dirs: { type: 'boolean', description: 'Include bounded forge temporary directory scan. Defaults to true.' },
+    cleanup_preview: { type: 'boolean', description: 'Return a no-side-effect cleanup plan for orphan workers and stale temp entries.' },
+  }),
+  definition('capability_recovery_probe', 'Read-only Runtime diagnostic evidence. This tool never starts, stops, restarts, repairs, or replaces Runtime modules.', {
+    repo_id: repoId,
+    recent_errors: { type: 'array', items: { type: 'string' } },
+    command_preview_available: { type: 'boolean' },
+    command_execute_available: { type: 'boolean' },
+    issue_tools_available: { type: 'boolean' },
+    job_tools_available: { type: 'boolean' },
+  }),
+  definition('capability_recovery_plan', 'Return a diagnostic handoff plan without Runtime lifecycle actions or automatic source repair.', {
+    repo_id: repoId,
+    recent_errors: { type: 'array', items: { type: 'string' } },
+  }),
+  definition('capability_recovery_apply', 'Apply one currently supported bounded recovery action after explicit authorization. Runtime lifecycle actions are outside this surface.', {
+    repo_id: repoId,
+    action_id: { type: 'string' },
+    confirm_authorization: { type: 'boolean' },
+    authorization: { type: 'string', description: 'Must equal action_id for actions that require authorization.' },
+    reason: { type: 'string' },
+    min_age_minutes: { type: 'number' },
+    max_candidates: { type: 'number' },
+  }, ['action_id'], false),
+  definition('runtime_maintenance_status', 'Read the self-contained runtime maintenance plan without using repository_command_execute or Local Job tickets.', {
+    repo_id: repoId,
+    min_age_minutes: { type: 'number' },
+    max_candidates: { type: 'number' },
+    cancel_pending_approvals: { type: 'boolean' },
+  }),
+  definition('runtime_maintenance_apply', 'Apply one bounded runtime maintenance action without repository_command_execute or Local Job tickets.', {
+    repo_id: repoId,
+    action_id: { type: 'string', enum: ['local_jobs_reconcile', 'quarantine_unreadable_local_jobs', 'runtime_storage_finalize_relocation', 'rebuild_projection', 'full_maintenance_pass'] },
+    confirm_maintenance: { type: 'boolean' },
+    authorization: { type: 'string', description: 'Must equal action_id.' },
+    min_age_minutes: { type: 'number' },
+    max_candidates: { type: 'number' },
+    cancel_pending_approvals: { type: 'boolean' },
+  }, ['action_id', 'confirm_maintenance', 'authorization'], false),
+  definition('workspace_auth_status', 'Summarize Workspace/Gmail auth readiness without returning or persisting secrets.', {
+    repo_id: repoId,
+  }),
+  definition('workspace_auth_login_prepare', 'Prepare a state-protected local Google Workspace/Gmail OAuth login with PKCE and Keychain persistence.', {
+    repo_id: repoId,
+    service: { type: 'string', enum: ['gmail', 'calendar', 'tasks', 'google-workspace'] },
+    scopes: { type: 'array', items: { type: 'string' } },
+    redirect_uri: { type: 'string' },
+  }),
+  definition('external_filesystem_targets_list', 'List pre-authorized external filesystem targets. Does not expose arbitrary absolute-path access.', {
+    repo_id: repoId,
+  }),
+  definition('external_filesystem_grant_preview', 'Preview a read-only external filesystem grant for a narrow absolute directory without writing config.', {
+    repo_id: repoId,
+    grant_key: { type: 'string' },
+    root_path: { type: 'string' },
+    mode: { type: 'string', enum: ['read', 'copy_into_repo'] },
+    expires_in_minutes: { type: 'number', description: 'Optional expiry in minutes, capped at 24h. Defaults to 8h.' },
+    reason: { type: 'string' },
+  }, ['grant_key', 'root_path', 'reason']),
+  definition('external_filesystem_grant_apply', 'Apply a previously previewed read-only external filesystem grant with explicit authorization.', {
+    repo_id: repoId,
+    grant_key: { type: 'string' },
+    root_path: { type: 'string' },
+    mode: { type: 'string', enum: ['read', 'copy_into_repo'] },
+    expires_in_minutes: { type: 'number', description: 'Optional expiry in minutes, capped at 24h. Defaults to 8h.' },
+    reason: { type: 'string' },
+    preview_ticket_id: { type: 'string' },
+    confirm_authorization: { type: 'boolean' },
+  }, ['grant_key', 'root_path', 'reason', 'preview_ticket_id', 'confirm_authorization'], false),
+  definition('external_filesystem_text_snapshot', 'Read a bounded text/directory snapshot from a pre-authorized external filesystem target key.', {
+    repo_id: repoId,
+    target_key: { type: 'string' },
+    path: { type: 'string' },
+    max_chars: { type: 'number' },
+  }, ['target_key']),
+  definition('runtime_storage_repair_preview', 'Preview repo-scoped local-jobs runtime storage repair candidates without mutation.', {
+    repo_id: repoId,
+    min_age_minutes: { type: 'number' },
+    max_candidates: { type: 'number' },
+  }),
+  definition('runtime_storage_repair_apply', 'Apply safe repo-scoped local-jobs runtime storage repairs after explicit confirmation.', {
+    repo_id: repoId,
+    candidate_ids: { type: 'array', items: { type: 'string' } },
+    min_age_minutes: { type: 'number' },
+    max_candidates: { type: 'number' },
+    confirm_repair: { type: 'boolean' },
+  }, ['confirm_repair'], false),
+  definition('list_plugins', 'List repository plugins, or controller-scoped plugins when repo_id is omitted.', {
+    repo_id: repoId,
+  }),
+  definition('get_plugin', 'Read one repository or controller-scoped plugin manifest including action schemas and policy requirements.', {
+    repo_id: repoId,
+    plugin_id: { type: 'string' },
+  }, ['plugin_id']),
+  definition('plugin_action_execute', 'Execute one typed repository or controller-scoped plugin action through the plugin provider authority. rh_context exposes plugin schemas/policy; rh_work does not execute plugin capabilities. For confirmation=authorization, normal host permission is authoritative and an exact-target Forge capability grant may be reused; do not set confirm_authorization merely because an ordinary authorization-class action was previously allowed. Strong-confirmation actions still require their explicit confirmation contract.', {
+    repo_id: repoId,
+    plugin_id: { type: 'string' },
+    action_id: { type: 'string' },
+    request_id: { type: 'string' },
+    work_id: { type: 'string', description: 'Optional existing remote-effect Work that should own the successful typed plugin receipt.' },
+    arguments: { type: 'object' },
+    timeout_ms: { type: 'number' },
+    confirm_authorization: { type: 'boolean', description: 'Explicit confirmation flag for strong_confirmation actions. Ordinary confirmation=authorization actions follow the host permission model and do not require this field.' },
+    confirmation_text: { type: 'string', description: 'Exact confirmation text for strong_confirmation actions only.' },
+  }, ['plugin_id', 'action_id', 'request_id'], false),
+  definition('toolchain_plugin_summary', 'Return a redacted, low-interception plugin summary without raw config files or full action schemas.', {
+    repo_id: repoId,
+    plugin_id: { type: 'string' },
+  }, ['plugin_id']),
+  definition('work_result_summary', 'Return a redacted job result summary with failure class and suggested next actions. Does not return raw stdout or stderr.', {
+    repo_id: repoId,
+    job_id: { type: 'string' },
+  }, ['job_id']),
+  definition('work_status_digest', 'Return a redacted work status digest using a neutral work_ref. Does not return raw stdout or stderr.', {
+    repo_id: repoId,
+    work_ref: { type: 'string' },
+  }, ['work_ref']),
+  definition('model_clients_summary', 'List enabled model clients and DeepSeek adapter configuration state. Policy remains enforced by forge.', {
+    repo_id: repoId,
+  }),
+  definition('model_control_plane_summary', 'Summarize primary and backup model controllers, handoff modes, and concurrency policy.', {
+    repo_id: repoId,
+  }),
+  definition('deepseek_tool_manifest', 'Return DeepSeek function-calling tool manifests for the low-interception forge surface.', {
+    repo_id: repoId,
+  }),
+  definition('deepseek_tool_call_prepare', 'Translate one DeepSeek function call into a forge operation without executing it.', {
+    repo_id: repoId,
+    function_name: { type: 'string' },
+    function_arguments: { type: 'object' },
+  }, ['function_name', 'function_arguments']),
+  definition('deepseek_controller_manifest', 'Return DeepSeek backup-controller manifest, boundaries, and function tools.', {
+    repo_id: repoId,
+  }),
+  definition('deepseek_controller_handoff_prepare', 'Prepare a safe DeepSeek backup-controller handoff packet without calling the external model.', {
+    repo_id: repoId,
+    reason: { type: 'string', enum: ['manual', 'chatgpt_platform_blocked', 'chatgpt_unavailable', 'parallel_review', 'local_gui_request'] },
+    objective: { type: 'string' },
+    current_controller: { type: 'string' },
+    blocked_tool_name: { type: 'string' },
+    recent_safe_error: { type: 'string' },
+  }),
+  definition('deepseek_controller_request_prepare', 'Prepare a DeepSeek chat-completions request for backup controller mode without sending it.', {
+    repo_id: repoId,
+    reason: { type: 'string', enum: ['manual', 'chatgpt_platform_blocked', 'chatgpt_unavailable', 'parallel_review', 'local_gui_request'] },
+    objective: { type: 'string' },
+    user_message: { type: 'string' },
+    current_controller: { type: 'string' },
+    blocked_tool_name: { type: 'string' },
+    recent_safe_error: { type: 'string' },
+    model: { type: 'string' },
+  }),
+  definition('review_artifacts_prepare', 'Create bounded repo-local review artifact roots for browser/iOS screenshot review workflows.', { repo_id: repoId }, [], false),
+  definition('review_artifacts_index', 'Index bounded repo-local browser/iOS screenshots, logs, and build reports for visual review.', { repo_id: repoId, limit: { type: 'number' } }),
+  definition('browser_review_packet', 'Build a browser visual review packet from indexed browser screenshots.', { repo_id: repoId, limit: { type: 'number' } }),
+  definition('ios_review_packet', 'Build or capture an iOS visual review packet from simulator screenshots and logs.', {
+    repo_id: repoId,
+    udid: { type: 'string' },
+    label: { type: 'string' },
+    capture: { type: 'boolean' },
+    limit: { type: 'number' },
+  }, [], false),
+  definition('workflow_watchdog_report', 'Diagnose stuck repository workflows across execution jobs, local bridge jobs, schedules, and runtime processes.', {
+    repo_id: repoId,
+    stale_minutes: { type: 'number' },
+    include_processes: { type: 'boolean' },
+  }),
+  definition('ios_xcode_status', 'Check local Xcode, xcodebuild, and simctl availability without mutation.', { repo_id: repoId }),
+  definition('ios_simulators_list', 'List available iOS Simulator devices using structured simctl JSON output.', {
+    repo_id: repoId,
+    runtime: { type: 'string' },
+    name: { type: 'string' },
+  }),
+  definition('ios_project_discover', 'Discover iOS workspaces, projects, Package.swift, and Info.plist files inside the repository.', { repo_id: repoId }),
+  definition('ios_schemes_list', 'List Xcode schemes for a repository-bounded workspace or project.', {
+    repo_id: repoId,
+    workspace: { type: 'string' },
+    project: { type: 'string' },
+  }),
+  definition('ios_simulator_boot', 'Boot an explicitly selected iOS Simulator UDID. Requires authorization.', {
+    repo_id: repoId,
+    udid: { type: 'string' },
+    open_simulator: { type: 'boolean' },
+    confirm_authorization: { type: 'boolean' },
+    timeout_ms: { type: 'number' },
+  }, ['udid', 'confirm_authorization'], false),
+  definition('ios_app_build', 'Build an iOS app into .forge/ios/DerivedData using xcodebuild structured arguments.', {
+    repo_id: repoId,
+    scheme: { type: 'string' },
+    udid: { type: 'string' },
+    workspace: { type: 'string' },
+    project: { type: 'string' },
+    configuration: { type: 'string' },
+    timeout_ms: { type: 'number' },
+  }, ['scheme'], false),
+  definition('ios_app_install', 'Install a bounded .app product from .forge/ios/DerivedData into a booted simulator. Requires authorization.', {
+    repo_id: repoId,
+    udid: { type: 'string' },
+    app_path: { type: 'string' },
+    confirm_authorization: { type: 'boolean' },
+  }, ['udid', 'app_path', 'confirm_authorization'], false),
+  definition('ios_app_launch', 'Launch a simulator app by bundle id with structured launch arguments. Requires authorization.', {
+    repo_id: repoId,
+    udid: { type: 'string' },
+    bundle_id: { type: 'string' },
+    arguments: { type: 'array', items: { type: 'string' } },
+    confirm_authorization: { type: 'boolean' },
+  }, ['udid', 'bundle_id', 'confirm_authorization'], false),
+  definition('ios_simulator_screenshot', 'Capture a simulator screenshot to .forge/ios/screenshots as a bounded artifact.', {
+    repo_id: repoId,
+    udid: { type: 'string' },
+    label: { type: 'string' },
+  }, ['udid'], false),
+  definition('ios_simulator_log_tail', 'Collect a bounded recent simulator log tail into .forge/ios/logs.', {
+    repo_id: repoId,
+    udid: { type: 'string' },
+    process: { type: 'string' },
+    last: { type: 'string' },
+    max_bytes: { type: 'number' },
+  }),
+  definition('ios_ui_smoke_test', 'Compose build, boot, launch, screenshot, and bounded logs for simulator UI review. Requires authorization.', {
+    repo_id: repoId,
+    udid: { type: 'string' },
+    scheme: { type: 'string' },
+    bundle_id: { type: 'string' },
+    workspace: { type: 'string' },
+    project: { type: 'string' },
+    configuration: { type: 'string' },
+    app_path: { type: 'string' },
+    screenshot_label: { type: 'string' },
+    confirm_authorization: { type: 'boolean' },
+  }, ['udid', 'scheme', 'bundle_id', 'confirm_authorization'], false),
+  definition('runtime_cleanup_preview', 'Preview stale forge temp directories, terminal local jobs, and historical attention cleanup candidates.', {
+    repo_id: repoId,
+    min_age_minutes: { type: 'number' },
+    include_temp_dirs: { type: 'boolean' },
+    include_terminal_local_jobs: { type: 'boolean' },
+    include_legacy_runs: { type: 'boolean' },
+    include_historical_attention: { type: 'boolean' },
+    max_candidates: { type: 'number' },
+  }),
+  definition('runtime_cleanup_apply', 'Apply safe cleanup candidates. Requires confirm_cleanup=true and remains limited to explicit forge candidates.', {
+    repo_id: repoId,
+    min_age_minutes: { type: 'number' },
+    include_temp_dirs: { type: 'boolean' },
+    include_terminal_local_jobs: { type: 'boolean' },
+    include_legacy_runs: { type: 'boolean' },
+    include_historical_attention: { type: 'boolean' },
+    max_candidates: { type: 'number' },
+    confirm_cleanup: { type: 'boolean' },
+  }, [], false),
+  definition('request_release_gate', 'Return an explicit external-Controller handoff for release evidence. Push, tag, and publish remain separately authorized.', { repo_id: repoId, request_id: { type: 'string' } }, [], false),
+];
+
+export const connectorExposedTools = runtimeToolDefinitions.map((tool) => tool.name);
+export const currentCallableTools = new Set(connectorExposedTools);