@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -0,0 +1,574 @@
+import type { McpToolDefinition } from '../../../packages/protocols/mcp/tool-contract';
+import { CONTROLLER_CONTEXT_IMPACT_DOMAINS } from '../../../src/cli/controller/context/types';
+import { RH_WORK_MODEL_OPERATIONS } from '../../../src/runtime/control-plane/facade/rh-work-operation-contract';
+import { CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS } from '../../../src/runtime/context/automatic-learning';
+
+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.' },
+    include_maintenance: { type: 'boolean', description: 'For detail reads only. Runs the explicit bounded maintenance inspection; defaults to false so status remains a hot read.' },
+    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: instance-level UserRequest inbox for genuine human actions/decisions. Repository-scoped handoff_id remains a legacy compatibility lookup.', {
+    repo_id: { ...repoId, description: 'Optional legacy repository context. Omit for canonical instance-level UserRequest operations.' },
+    operation: { type: 'string', enum: ['list', 'get', 'ack', 'accept', 'resolve', 'dismiss', 'create'], description: 'Defaults to list (pending).' },
+    request_id: { type: 'string', description: 'Canonical instance-level UserRequest id.' },
+    handoff_id: { type: 'string', description: 'Legacy compatibility id.' },
+    work_id: { type: 'string' },
+    title: { type: 'string' },
+    reason: { type: 'string' },
+    summary: { type: 'string' },
+    recommended_decision: { type: 'string' },
+    recommended_prompt: { type: 'string' },
+    action_required: { type: 'string', enum: ['login', 'grant_permission', 'confirm_destructive', 'product_decision'] },
+    request_kind: { type: 'string', enum: ['user_action_request', 'user_decision_request'] },
+    root_cause_key: { 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. Semantic task/capability queries can also recall an initial bounded, relevance-gated Cognitive advisory working set when Project/Workspace scope is available. That first pack is an attention envelope, never a claim that the top N items are cognitively complete. Reuse it through routine micro-steps; when the model judges prior context insufficient, progressively narrow/expand recall with another semantic query or explicit knowledge audit. 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.' },
+    include_learning_recall: { type: 'boolean', description: 'Defaults to true for semantic task/capability queries. Set false for routine progressive source follow-ups or micro-steps when the already recalled working set is still valid. This is a model-owned attention/cadence choice, not a Forge semantic trigger.' },
+    knowledge_query: { type: 'string', description: 'Optional explicit read-only Cognitive audit query. Ordinary code/capability intent queries already receive a bounded relevant-learning recall; use this field for deliberate memory inspection. May be used without code query. Use "*" or omit text with filters to list learned advisory memory in scopes reachable from this repo/Work.' },
+    knowledge_memory_id: { type: 'string', description: 'Optional exact Cognitive memory id for inspection.' },
+    knowledge_scope_kind: { type: 'string', enum: ['work', 'requirement', 'plan', 'plan_step', 'project', 'workspace'], description: 'Optional Cognitive scope filter; it must already be reachable from the selected repo/Work.' },
+    knowledge_scope_id: { type: 'string', description: 'Optional Cognitive scope id paired with knowledge_scope_kind.' },
+    knowledge_concept: { type: 'string', description: 'Optional exact learned concept filter.' },
+    knowledge_facet: { type: 'string', description: 'Optional exact learned facet filter.' },
+    knowledge_source_kind: { type: 'string', enum: ['experience', 'outcome', 'knowledge', 'controller', 'system', 'external'], description: 'Optional provenance source-kind filter.' },
+    knowledge_source_work_id: { type: 'string', description: 'Optional provenance source Work filter.' },
+    knowledge_limit: { type: 'number', minimum: 1, maximum: 100, description: 'Per-call read envelope for explicit Cognitive audit/expansion; defaults to 24. This is a context/transport budget, not a semantic claim that N memories are sufficient.' },
+    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 a short-lived release-owned Language Service sidecar so compiler/project allocator growth never remains resident in the canonical Runtime; 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 optional durable Requirement/Plan/Work semantic context, explicit recovery, scheduling/workflow intent, and external controller launch. Ordinary execution and validation use direct domain capabilities; provider/session binding, retries, transport recovery, dedupe, and other mechanical bookkeeping stay internal.', {
+    repo_id: repoId,
+    checkout_id: { type: 'string', description: 'Optional checkout identity for exact Work and Plan source selection.' },
+    operation: { type: 'string', enum: [...RH_WORK_MODEL_OPERATIONS], description: 'Defaults to start. list reads current semantic Work plus a bounded recent terminal history for the selected repository; start creates semantic Work context only. Requirement, Plan, and Work remain model-authored durable semantic records; execution and validation use direct capabilities. Work completion is an explicit semantic update rather than an execution phase transition.' },
+    limit: { type: 'number', minimum: 1, maximum: 100, description: 'Bounded result limit for list operations.' },
+    objective: { type: 'string' },
+    capability_id: { type: 'string', description: 'Compatibility-only carrier. Current callers should use typed rh_work fields directly. The outer adapter accepts only the bounded frozen semantic.v1 bridge and current-conversation enrollment, validates them without persistence, and routes them into the same Thin owners.' },
+    work_id: { type: 'string' },
+    workflow_id: { type: 'string', description: 'Versioned Workflow asset identity for workflow_execute/workflow_reconcile.' },
+    workflow_run_id: { type: 'string', description: 'Stable run identity. Reusing it resumes only the exact same workflow/content/input identity.' },
+    workflow_inputs: { type: 'object', description: 'Typed Workflow inputs validated against the installed asset contract.' },
+    workflow_scope_project_id: { type: 'string', description: 'Optional project-scoped Workflow registry identity. First-party Xiaohongshu assets use controller scope and still validate the owning Work project/account inputs.' },
+    workflow_reconciliation_request_id: { type: 'string', description: 'Fresh idempotency identity for one reconciliation observation. Retry the same observation with the same id; use a new id only for a later observation.' },
+    requirement_id: { type: 'string', description: 'Stable Requirement identity for requirement_get/requirement_revise/requirement_create or optional semantic context link for Work/Plan.' },
+    expected_revision: { type: 'number', minimum: 1, description: 'Expected current semantic revision for requirement_revise, plan_revise, revise, or complete. Stale writers fail and return current state; Forge never performs an implicit merge.' },
+    work_state: { type: 'string', enum: ['open', 'completed', 'cancelled'], description: 'Thin semantic Work state for revise.' },
+    work_result_refs: { type: 'array', maxItems: 100, uniqueItems: true, items: { type: 'string', maxLength: 512 }, description: 'Model/user-selected result references for thin semantic Work; separate from mechanical evidence and delivery receipts.' },
+    semantic_parent_work_id: { type: 'string', minLength: 1, maxLength: 256, description: 'Optional objective-decomposition parent for primary semantic Work. Distinct from execution parentWorkId and continuation lineage.' },
+    depends_on_work_ids: { type: 'array', maxItems: 32, uniqueItems: true, items: { type: 'string', minLength: 1, maxLength: 256 }, description: 'Explicit semantic ordering dependencies for primary Work. No edge means siblings may proceed independently; this field never dispatches or blocks Scheduler execution by itself.' },
+    requirement_revision: { type: 'number', minimum: 1, description: 'Work start defaults to selected Requirement head; Work revise explicitly adopts an existing semantic revision via expected_revision CAS, including historical revisions. For Plan, optional provenance.' },
+    plan_revision: { type: 'number', minimum: 1, description: 'Work start defaults to selected Plan head; Work revise explicitly adopts an existing semantic revision via expected_revision CAS, including historical revisions. Work get compares adopted and current heads without rebinding.' },
+    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.' },
+    requirement_state: { type: 'string', enum: ['open', 'completed', 'cancelled'], description: 'Thin semantic Requirement state for requirement_revise.' },
+    requirement_candidate_id: { type: 'string', description: 'Exact Cognitive memory id for operation=requirement_promote_candidate.' },
+    handoff_id: { type: 'string', description: 'Optional existing HandoffItem to include as bounded context for launcher_start.' },
+    learning_signals: { type: 'array', maxItems: CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS, items: { type: 'object', additionalProperties: false,
+      properties: {
+        scope_kind: { type: 'string', enum: ['work', 'requirement', 'project', 'workspace'] },
+        kind: { type: 'string', maxLength: 64, description: 'Compact model-authored descriptive kind (for example principle, procedure, product-model, architecture-pattern). This vocabulary is open and never an admission gate.' },
+        valence: { type: 'string', enum: ['positive', 'negative', 'neutral'] },
+        summary: { type: 'string', maxLength: 2000 },
+        concepts: { type: 'array', minItems: 1, maxItems: 32, uniqueItems: true, items: { type: 'string', maxLength: 256 } },
+        facets: { type: 'array', maxItems: 12, uniqueItems: true, items: { type: 'string', maxLength: 128 } },
+        admission_source: { type: 'string', enum: ['explicit_human', 'controller_observation', 'system_inference'] },
+        portability: { type: 'string', enum: ['local', 'portable'] },
+        salience: { type: 'number', minimum: 0, maximum: 1 },
+        confidence: { type: 'number', minimum: 0, maximum: 1 },
+        utility: { type: 'number', minimum: 0, maximum: 1 },
+        evidence_refs: { type: 'array', maxItems: 16, uniqueItems: true, items: { type: 'string', maxLength: 512 } },
+        counter_evidence_refs: { type: 'array', maxItems: 16, uniqueItems: true, items: { type: 'string', maxLength: 512 } },
+        expires_at: { type: 'string' },
+      },
+      required: ['scope_kind', 'kind', 'valence', 'summary', 'concepts', 'admission_source', 'portability', 'salience', 'confidence', 'utility'] },
+      description: 'Model-authored semantic deltas, never keyword/phrase-derived lessons. The array bound is only one MCP transport envelope; it is not a per-interaction learning quota. With operation=learning_record, project/workspace learning is lifecycle-free; when work_id is selected, its server-derived reachable Work/Requirement scopes are also available through the same writer. Distill reusable judgement/procedure/product/architecture knowledge rather than copying raw transcripts or source prose.' },
+    learning_feedback: { type: 'array', maxItems: 32, items: { type: 'object', additionalProperties: false,
+      properties: {
+        memory_address: { type: 'string', maxLength: 1024, description: 'Exact stable memoryId/address returned by learningRecall or Cognitive audit.' },
+        decision: { type: 'string', enum: ['used', 'rejected'] },
+        reason: { type: 'string', maxLength: 1000 },
+        rejection_kind: { type: 'string', enum: ['irrelevant', 'stale', 'contradicted'], description: 'Required only for rejected feedback. Semantic classification is model-authored, never inferred from keywords.' },
+      },
+      required: ['memory_address', 'decision', 'reason'] },
+      description: 'Lifecycle-free advisory retrieval feedback for operation=learning_feedback. The current principal/session and repository-reachable Cognitive scope are server-derived; feedback influences retrieval utility only and never factual confidence or execution authority.' },
+    outcome_observation: { type: 'object', description: 'Typed Work-specific OutcomeObservation draft for outcome_record. Work semantic provenance is derived server-side and cannot be supplied by the caller.' },
+    experience_draft: { type: 'object', description: 'Typed verified Work Experience draft for experience_record. Generic teaching/correction belongs in learning_record instead; source provenance is derived from current Work semantic context.' },
+    quality_adjustment_fingerprint: { type: 'string', description: 'Optional quality adjustment fingerprint for experience_record when backed by verified evidence.' },
+    controller_type: { type: 'string', enum: ['chatgpt', 'codex', 'grok', 'claude'], description: 'External controller kind for launcher_start.' },
+    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.' },
+    transport_conversation: { type: 'string', enum: ['bound', 'fresh'], description: 'ChatGPT launcher transport only. When omitted, an existing Work binding or explicit conversation_url is reused; otherwise a fresh conversation is created. bound requires an existing binding or explicit conversation_url. fresh always starts a new conversation and records transport metadata after provider delivery is observed.' },
+    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' },
+    superseded_by: { type: 'string', description: 'For plan_revise only: record the one-way successor Plan lineage. Once set it cannot be cleared or redirected; current Plan listings exclude the predecessor without restoring legacy Plan lifecycle semantics.' },
+    scope_key: { type: 'string', description: 'Optional normalized semantic scope label for Plan discovery/lineage; it is not execution ownership or a repository mutex.' },
+    source_revision: { type: 'string', description: 'Repository revision observed during read-only planning preflight.' },
+    plan_items: { type: 'array', maxItems: 100, items: { type: 'object', required: ['id', 'objective'], additionalProperties: false, properties: { id: { type: 'string', maxLength: 200 }, objective: { type: 'string', maxLength: 2000 }, dependencies: { type: 'array', maxItems: 100, items: { type: 'string', maxLength: 200 } } } }, description: 'Thin model-authored Plan items for plan_create/plan_revise. Items are descriptive working memory only and never own paths, checks, Work, scheduling, or acceptance.' },
+    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' },
+    approval_confirmed: { type: 'boolean' },
+    dry_run: { type: 'boolean', description: 'Defaults to true for repair.' },
+    repair_operation: { type: 'string', enum: ['diagnose', 'repair', 'verify', 'handoff'] },
+    authorize_destructive_cleanup: { type: 'boolean' },
+    detail_level: { type: 'string', enum: ['summary', 'detail'] },
+    reason: { type: 'string', description: 'Bounded reason for a work stop or repair record.' },
+  }, [], false),
+  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/evidence handle by opaque id. repo_id is optional and used only to adopt a historical repository-partitioned handle once.', { artifact_id: { type: 'string' }, repo_id: { ...repoId, description: 'Legacy repository hint only. Omit for canonical ForgeInstance output handles.' }, max_bytes: { type: 'number' } }, ['artifact_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('computer_console_unlock_prepare', 'Prepare one protected console unlock without transporting a password through ChatGPT or Forge Runtime. Forge Desktop Operator displays a provider-local secure password field while the console is unlocked and returns only a short-lived opaque single-use handle. Requires confirm_authorization=true for every invocation.', {
+    confirm_authorization: { type: 'boolean', description: 'Must be true to authorize this exact one-shot local credential preparation.' },
+    timeout_ms: { type: 'number', description: 'Bounded provider/prompt timeout in milliseconds. Defaults to 15000 and is capped at 30000.' },
+  }, ['confirm_authorization'], false),
+  definition('computer_console_unlock', 'Protected one-shot console unlock through computer.console.unlock.v1 using only a provider-local opaque credential handle. Raw macOS credentials never enter MCP arguments, Forge Runtime, Plugin actions, Process/Work state, receipts, audit hashes, or replayable jobs. Requires confirm_authorization=true for every invocation.', {
+    credential_handle: { type: 'string', minLength: 36, maxLength: 64, description: 'Opaque short-lived single-use handle returned by computer_console_unlock_prepare. It is not a credential.' },
+    confirm_authorization: { type: 'boolean', description: 'Must be true to authorize this exact one-shot console unlock invocation.' },
+    timeout_ms: { type: 'number', description: 'Bounded provider/postcondition timeout in milliseconds. Defaults to 15000 and is capped at 30000.' },
+  }, ['credential_handle', 'confirm_authorization'], false),
+  definition('computer_console_unlock_enroll', 'Enroll provider-local device-only protected console recovery. Credential material never enters ChatGPT, Forge Runtime, plugin receipts, or replayable jobs. Requires confirm_authorization=true for every invocation.', {
+    confirm_authorization: { type: 'boolean', description: 'Must be true to authorize this exact provider-local enrollment invocation.' },
+    timeout_ms: { type: 'number', description: 'Bounded provider timeout in milliseconds. Defaults to 15000 and is capped at 30000.' },
+  }, ['confirm_authorization'], false),
+  definition('computer_console_unlock_status', 'Read protected console recovery enrollment and availability without exposing provider-local credential material. Requires confirm_authorization=true for every invocation.', {
+    confirm_authorization: { type: 'boolean', description: 'Must be true to authorize this exact protected status invocation.' },
+    timeout_ms: { type: 'number', description: 'Bounded provider timeout in milliseconds. Defaults to 15000 and is capped at 30000.' },
+  }, ['confirm_authorization'], false),
+  definition('computer_console_unlock_recover', 'Recover a locked macOS console using only previously enrolled provider-local device-only credential material. No credential is transported through ChatGPT or Forge Runtime. Requires confirm_authorization=true for every invocation.', {
+    confirm_authorization: { type: 'boolean', description: 'Must be true to authorize this exact one-shot recovery invocation.' },
+    timeout_ms: { type: 'number', description: 'Bounded provider/postcondition timeout in milliseconds. Defaults to 15000 and is capped at 30000.' },
+  }, ['confirm_authorization'], false),
+  definition('computer_console_unlock_revoke', 'Revoke provider-local protected console recovery enrollment. Requires confirm_authorization=true for every invocation.', {
+    confirm_authorization: { type: 'boolean', description: 'Must be true to authorize this exact provider-local revocation invocation.' },
+    timeout_ms: { type: 'number', description: 'Bounded provider timeout in milliseconds. Defaults to 15000 and is capped at 30000.' },
+  }, ['confirm_authorization'], false),
+  definition('capability_execute', 'Execute one typed Forge core capability through its canonical substrate owner. Discover the exact action schema with rh_context capability_id first. This stable facade prevents one top-level MCP tool per atomic repository operation; plugin capabilities continue to use plugin_action_execute.', {
+    repo_id: repoId,
+    checkout_id: { type: 'string', description: 'Optional exact checkout identity.' },
+    capability_id: { type: 'string', description: 'Exact core capability identity returned by rh_context.' },
+    action: { type: 'string', description: 'Exact capability action returned by rh_context.' },
+    request_id: { type: 'string', description: 'Stable idempotency identity for this invocation.' },
+    arguments: { type: 'object', description: 'Action-specific arguments validated by the capability owner.' },
+  }, ['capability_id', 'action', 'request_id'], false),
+  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('supervisor_task', 'Start, list, inspect, revise, recover, stop, or prove standalone Workflow Supervisor autonomous tasks. Supervisor task/effect state is the continuation authority; Requirement, Plan, and Work are optional and are not created by this tool.', {
+    repo_id: { ...repoId, description: 'Optional repository provenance for start/proof; never Work authority.' },
+    operation: { type: 'string', enum: ['start', 'list', 'get', 'revise', 'recover', 'stop', 'proof'] },
+    task_id: { type: 'string' },
+    objective: { type: 'string', description: 'Outcome objective for start/revise; revise never changes task or conversation identity.' },
+    expected_objective_sha256: { type: 'string', description: 'For revise: CAS hash of the exact current objective.' },
+    reason: { type: 'string', description: 'Operator reason recorded for stop/recover.' },
+    source_effect_id: { type: 'string', description: 'Optional exact source effect for operator recovery fencing.' },
+    supersede_unknown: { type: 'boolean', description: 'For recover only: explicitly retire one outcome-unknown effect instead of replaying it.' },
+    authorized_by: { type: 'string', description: 'Optional operator identity recorded by canonical recovery authority.' },
+    active_only: { type: 'boolean', description: 'For list, defaults true; exclude terminal tasks.' },
+    request_id: { type: 'string', description: 'Stable idempotency identity for start/revise/recover.' },
+    active_release_id: { type: 'string', description: 'Active Runtime release expected in proof dispatch evidence.' },
+    not_before: { type: 'string', description: 'ISO-8601 lower bound for proof completions.' },
+  }, ['operation'], false),
+  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);

package/adapters/mcp/runtime-gateway/runtime-tool-shared.ts

@@ -0,0 +1,27 @@
+import { boundedPluginArtifactImageContent, jsonPreview, result, resultWithPluginArtifactImages } from './result-adapter';
+import { expectedRevision, repositoryRootForRepoId, selected, stringList } from './shared-adapter';
+import type { ExecutionJob } from '../../../src/runtime/execution/jobs/types';
+import { readJobEvents } from '../../../src/runtime/evidence/event-ledger';
+import {
+  summarizeExecutionJobForMcp,
+  summarizeJobResultForLowInterception,
+  summarizePluginForLowInterception,
+} from '../../../src/runtime/safe-tooling';
+
+export function summarizeJobEvents(controllerHome: string, repoId: string, jobId: string): Array<Record<string, unknown>> {
+  const repoRoot = repositoryRootForRepoId(controllerHome, repoId);
+  return readJobEvents(controllerHome, repoId, jobId).slice(-20).map((event) => {
+    const dataPreview = event.data && Object.keys(event.data).length > 0 ? jsonPreview(event.data, 240, repoRoot ? [repoRoot] : []) : undefined;
+    return {
+      eventId: event.eventId,
+      eventType: event.eventType,
+      occurredAt: event.occurredAt,
+      revision: event.revision,
+      ...(dataPreview ? { dataPreview: dataPreview.preview, dataTruncated: dataPreview.truncated } : {}),
+    };
+  });
+}
+
+export function summarizeExecutionJob(job: ExecutionJob, repoRoot?: string): Record<string, unknown> {
+  return summarizeExecutionJobForMcp(job, repoRoot);
+}