Phase A0: sim half of the mship↔CLI translation layer — primitives only

lib/mothership/agent-cli/ executes the worker typed AgentCliRequest and
nothing more: request-schema validates it, run-cli runs the embedded CLI
(with the @token sandbox reads), pipeline applies already-parsed grep
stages, sink lands stdout on the machine, and engines/ holds the
augmentation engines keyed by the worker canonical names. The sim-side
matcher, flag parser, pipe splitter, and help merge are deleted — the
grammar lives in the mothership worker now, which is closed source and the
one place a command meaning is decided.

The sim_cli handler becomes a thin adapter: validate the request, execute,
return the raw result. It refuses a frame without the typed request rather
than falling back to re-parsing argv, so the worker must deploy first.

scripts/check-agent-cli-boundary.ts (bun run check:agent-cli-boundary)
holds the line: primitives-only export surface, no pipe/flag/command-name
grammar under lib/mothership, runEmbeddedCli reachable only through the
primitive runner, and no agent imports in the public CLI package.

lib/mothership/generated/agent-cli.ts is the synced contract copy.

https://claude.ai/code/session_01HFVhPDtRZuCgupPco633w8

Author: Sg312

apps/sim/lib/mothership/agent-cli/engines.test.ts

@@ -0,0 +1,197 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it, vi } from 'vitest'
+
+const { buildWorkflowLintReport } = vi.hoisted(() => ({
+  buildWorkflowLintReport: vi.fn().mockResolvedValue({
+    sources: ['block-1'],
+    sinks: ['block-2'],
+    orphanBlocks: [],
+    emptyOutgoingPorts: [],
+    invalidBranchPorts: [],
+    invalidConnectionTargets: [],
+    fieldIssues: [
+      {
+        blockId: 'block-2',
+        blockName: 'Summarize emails',
+        missingRequiredFields: ['model'],
+        inactiveModeValues: [],
+      },
+    ],
+    unresolvedReferences: [],
+  }),
+}))
+
+vi.mock('@/lib/workflows/editing/lint-report', () => ({ buildWorkflowLintReport }))
+
+import { runEngine } from '@/lib/mothership/agent-cli/engines'
+import type { AgentCliRuntime } from '@/lib/mothership/agent-cli/types'
+
+const WORKFLOW_STATE = {
+  blocks: {
+    'block-1': { type: 'starter', name: 'Start', enabled: true },
+    'block-2': { type: 'agent', name: 'Summarize emails', enabled: true },
+  },
+  edges: [{ source: 'block-1', target: 'block-2', sourceHandle: 'source', id: 'edge-1' }],
+  variables: { apiBase: 'https://api.example.com' },
+}
+
+function runtimeWith(responses: Record<string, unknown>): AgentCliRuntime {
+  return {
+    workspaceId: 'ws-1',
+    userId: 'user-1',
+    client: {
+      request: async <T>(path: string): Promise<T> => {
+        const hit = responses[path]
+        if (hit === undefined) throw new Error(`Unexpected request: ${path}`)
+        return hit as T
+      },
+    },
+  }
+}
+
+const EXPORT_PATH = '/api/v2/workflows/wf-1/export'
+const exportResponse = { data: { state: WORKFLOW_STATE } }
+
+describe('workflow views', () => {
+  it('projects just the blocks', async () => {
+    const result = await runEngine(
+      'workflow blocks',
+      ['wf-1'],
+      runtimeWith({ [EXPORT_PATH]: exportResponse }),
+      {}
+    )
+    expect(result.exitCode).toBe(0)
+    const blocks = JSON.parse(result.stdout)
+    expect(blocks).toEqual([
+      { id: 'block-1', type: 'starter', name: 'Start', enabled: true },
+      { id: 'block-2', type: 'agent', name: 'Summarize emails', enabled: true },
+    ])
+  })
+
+  it('projects just the edges', async () => {
+    const result = await runEngine(
+      'workflow edges',
+      ['wf-1'],
+      runtimeWith({ [EXPORT_PATH]: exportResponse }),
+      {}
+    )
+    expect(result.exitCode).toBe(0)
+    expect(JSON.parse(result.stdout)).toEqual([
+      { source: 'block-1', target: 'block-2', sourceHandle: 'source' },
+    ])
+  })
+
+  it('fails usefully without a workflow id', async () => {
+    const result = await runEngine('workflow blocks', [], runtimeWith({}), {})
+    expect(result.exitCode).toBe(1)
+    expect(result.stderr).toContain('Usage:')
+  })
+})
+
+describe('files grep', () => {
+  const FILES_LIST = {
+    data: [
+      { id: 'f1', name: 'report.md', folderPath: 'docs' },
+      { id: 'f2', name: 'logo.png', folderPath: '' },
+    ],
+    nextCursor: null,
+  }
+  const readText = (text: string, degraded = false) => ({
+    data: { text, degraded },
+  })
+
+  it('greps file contents with line numbers, skipping non-text files', async () => {
+    const result = await runEngine(
+      'files grep',
+      ['quarterly'],
+      runtimeWith({
+        '/api/v2/files': FILES_LIST,
+        '/api/v2/files/f1/text': readText('# Report\nQuarterly revenue was up.\n'),
+        '/api/v2/files/f2/text': readText('', true),
+      }),
+      {}
+    )
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('docs/report.md:2: Quarterly revenue was up.')
+    expect(result.stdout).not.toContain('logo.png')
+  })
+
+  it('filters by folder prefix', async () => {
+    const result = await runEngine(
+      'files grep',
+      ['Quarterly', 'other'],
+      runtimeWith({ '/api/v2/files': FILES_LIST }),
+      {}
+    )
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('No matches')
+  })
+})
+
+describe('workflow grep', () => {
+  it('reports matches as path: value lines', async () => {
+    const result = await runEngine(
+      'workflow grep',
+      ['wf-1', 'Summarize'],
+      runtimeWith({ [EXPORT_PATH]: exportResponse }),
+      {}
+    )
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('.blocks.block-2.name: Summarize emails')
+  })
+
+  it('falls back to literal search on an invalid regex', async () => {
+    const result = await runEngine(
+      'workflow grep',
+      ['wf-1', 'api.example.com['],
+      runtimeWith({ [EXPORT_PATH]: exportResponse }),
+      {}
+    )
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toBe('No matches.')
+  })
+
+  it('searches across all workspace workflows', async () => {
+    const result = await runEngine(
+      'workflows grep',
+      ['Summarize'],
+      runtimeWith({
+        '/api/v2/workflows': {
+          data: [{ id: 'wf-1', name: 'Email digest' }],
+          nextCursor: null,
+        },
+        [EXPORT_PATH]: exportResponse,
+      }),
+      {}
+    )
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('Email digest (wf-1).blocks.block-2.name: Summarize emails')
+  })
+
+  it('lints a workflow through the shared engine with the caller scoped as subject', async () => {
+    const result = await runEngine(
+      'workflow lint',
+      ['wf-1'],
+      runtimeWith({ [EXPORT_PATH]: exportResponse }),
+      {}
+    )
+    expect(result.stderr).toBe('')
+    expect(result.exitCode).toBe(0)
+    const report = JSON.parse(result.stdout)
+    expect(report.fieldIssues).toHaveLength(1)
+    expect(report.summary.length).toBeGreaterThan(0)
+    expect(buildWorkflowLintReport).toHaveBeenCalledWith(expect.anything(), {
+      workflowId: 'wf-1',
+      workspaceId: 'ws-1',
+      subjectUserId: 'user-1',
+    })
+  })
+
+  it('surfaces execution errors as a failed result, never a throw', async () => {
+    const result = await runEngine('workflow grep', ['wf-missing', 'x'], runtimeWith({}), {})
+    expect(result.exitCode).toBe(1)
+    expect(result.stderr).toContain('Unexpected request')
+  })
+})

…ools/handlers/agent-cli/commands/deps.ts …lib/mothership/agent-cli/engines/deps.tsapps/sim/lib/mothership/tools/handlers/agent-cli/commands/deps.ts renamed to apps/sim/lib/mothership/agent-cli/engines/deps.ts apps/sim/lib/mothership/tools/handlers/agent-cli/commands/deps.ts renamed to apps/sim/lib/mothership/agent-cli/engines/deps.ts

@@ -1,9 +1,5 @@
-import { fetchWorkflowState } from '@/lib/mothership/tools/handlers/agent-cli/commands/workflow-views'
-import {
-  type AgentCliCommand,
-  agentCliFail,
-  agentCliOk,
-} from '@/lib/mothership/tools/handlers/agent-cli/types'
+import { fetchWorkflowState } from '@/lib/mothership/agent-cli/engines/workflow-views'
+import { type AgentCliEngine, agentCliFail, agentCliOk } from '@/lib/mothership/agent-cli/types'
 import { normalizeName, SPECIAL_REFERENCE_PREFIXES } from '@/executor/constants'
 import {
   collectStringLeaves,
@@ -33,11 +29,7 @@ interface DepView {
   paths?: string[]
 }
 
-export const workflowDepsCommand: AgentCliCommand = {
-  path: ['workflow', 'deps'],
-  summary:
-    'List every reference one block consumes (upstream blocks, variables, env) — what to mock for an isolated run',
-  usage: 'workflow deps <workflowId> <blockId>',
+export const workflowDepsCommand: AgentCliEngine = {
   async execute(rest, runtime) {
     const [workflowId, blockId] = rest
     if (!workflowId || !blockId)

…andlers/agent-cli/commands/files-grep.ts …thership/agent-cli/engines/files-grep.tsapps/sim/lib/mothership/tools/handlers/agent-cli/commands/files-grep.ts renamed to apps/sim/lib/mothership/agent-cli/engines/files-grep.ts apps/sim/lib/mothership/tools/handlers/agent-cli/commands/files-grep.ts renamed to apps/sim/lib/mothership/agent-cli/engines/files-grep.ts

@@ -1,10 +1,10 @@
 import type { ListFilesResponse, ReadFileTextResponse } from 'sim/embed'
 import {
-  type AgentCliCommand,
+  type AgentCliEngine,
   type AgentCliRuntime,
   agentCliFail,
   agentCliOk,
-} from '@/lib/mothership/tools/handlers/agent-cli/types'
+} from '@/lib/mothership/agent-cli/types'
 
 /**
  * Content grep across workspace files (the Go copilot's VFS-wide grep, files
@@ -59,10 +59,7 @@ async function listAllFiles(runtime: AgentCliRuntime): Promise<ListFilesResponse
   return rows.slice(0, MAX_FILES)
 }
 
-export const filesGrepCommand: AgentCliCommand = {
-  path: ['files', 'grep'],
-  summary: 'Search the content of every workspace file for a pattern',
-  usage: 'files grep <pattern> [folder-path-prefix]',
+export const filesGrepCommand: AgentCliEngine = {
   async execute(rest, runtime) {
     const [pattern, folderPrefix] = [rest[0], rest[1]]
     if (!pattern) return agentCliFail('Usage: sim files grep <pattern> [folder-path-prefix]')

…ools/handlers/agent-cli/commands/grep.ts …lib/mothership/agent-cli/engines/grep.tsapps/sim/lib/mothership/tools/handlers/agent-cli/commands/grep.ts renamed to apps/sim/lib/mothership/agent-cli/engines/grep.ts apps/sim/lib/mothership/tools/handlers/agent-cli/commands/grep.ts renamed to apps/sim/lib/mothership/agent-cli/engines/grep.ts

@@ -1,11 +1,11 @@
 import type { ListWorkflowsResponse } from 'sim/embed'
-import { fetchWorkflowState } from '@/lib/mothership/tools/handlers/agent-cli/commands/workflow-views'
+import { fetchWorkflowState } from '@/lib/mothership/agent-cli/engines/workflow-views'
 import {
-  type AgentCliCommand,
+  type AgentCliEngine,
   type AgentCliRuntime,
   agentCliFail,
   agentCliOk,
-} from '@/lib/mothership/tools/handlers/agent-cli/types'
+} from '@/lib/mothership/agent-cli/types'
 
 /**
  * Structural grep over workflow state. Matches walk the exported JSON tree and
@@ -62,10 +62,7 @@ function renderMatches(lines: string[]): string {
   return capped.join('\n')
 }
 
-export const workflowGrepCommand: AgentCliCommand = {
-  path: ['workflow', 'grep'],
-  summary: 'Search one workflow state (blocks, params, edges) for a pattern',
-  usage: 'workflow grep <workflowId> <pattern>',
+export const workflowGrepCommand: AgentCliEngine = {
   async execute(rest, runtime) {
     const [workflowId, ...patternParts] = rest
     const pattern = patternParts.join(' ')
@@ -92,10 +89,7 @@ async function listAllWorkflows(runtime: AgentCliRuntime): Promise<ListWorkflows
   return rows
 }
 
-export const workflowsGrepCommand: AgentCliCommand = {
-  path: ['workflows', 'grep'],
-  summary: 'Search every workflow in the workspace for a pattern',
-  usage: 'workflows grep <pattern>',
+export const workflowsGrepCommand: AgentCliEngine = {
   async execute(rest, runtime) {
     const pattern = rest.join(' ')
     if (!pattern) return agentCliFail('Usage: sim workflows grep <pattern>')

apps/sim/lib/mothership/agent-cli/engines/index.ts

@@ -0,0 +1,51 @@
+import { getErrorMessage } from '@sim/utils/errors'
+import { workflowDepsCommand } from '@/lib/mothership/agent-cli/engines/deps'
+import { filesGrepCommand } from '@/lib/mothership/agent-cli/engines/files-grep'
+import { workflowGrepCommand, workflowsGrepCommand } from '@/lib/mothership/agent-cli/engines/grep'
+import { workflowLintCommand } from '@/lib/mothership/agent-cli/engines/lint'
+import { logsQueryCommand } from '@/lib/mothership/agent-cli/engines/query'
+import { workflowTraceCommand } from '@/lib/mothership/agent-cli/engines/trace'
+import {
+  workflowBlocksCommand,
+  workflowEdgesCommand,
+} from '@/lib/mothership/agent-cli/engines/workflow-views'
+import {
+  type AgentCliEngine,
+  type AgentCliFlags,
+  type AgentCliResult,
+  type AgentCliRuntime,
+  agentCliFail,
+} from '@/lib/mothership/agent-cli/types'
+
+/**
+ * Every augmentation engine, keyed by the worker's canonical command name. The worker's
+ * registry (grammar/augmentations.ts) and this map must agree exactly — the worker's
+ * augmentation-drift check reads these keys.
+ */
+export const AUGMENTATION_ENGINES: Readonly<Record<string, AgentCliEngine>> = {
+  'files grep': filesGrepCommand,
+  'logs query': logsQueryCommand,
+  'workflow blocks': workflowBlocksCommand,
+  'workflow deps': workflowDepsCommand,
+  'workflow edges': workflowEdgesCommand,
+  'workflow grep': workflowGrepCommand,
+  'workflow lint': workflowLintCommand,
+  'workflow trace': workflowTraceCommand,
+  'workflows grep': workflowsGrepCommand,
+}
+
+/** Runs one engine by the worker's name; an engine that throws yields a failed result, never a throw. */
+export async function runEngine(
+  name: string,
+  positionals: string[],
+  runtime: AgentCliRuntime,
+  flags: AgentCliFlags
+): Promise<AgentCliResult> {
+  const engine = AUGMENTATION_ENGINES[name]
+  if (!engine) return agentCliFail(`No engine for agent command "${name}".`)
+  try {
+    return await engine.execute(positionals, runtime, flags)
+  } catch (error) {
+    return agentCliFail(getErrorMessage(error))
+  }
+}

…ools/handlers/agent-cli/commands/lint.ts …lib/mothership/agent-cli/engines/lint.tsapps/sim/lib/mothership/tools/handlers/agent-cli/commands/lint.ts renamed to apps/sim/lib/mothership/agent-cli/engines/lint.ts apps/sim/lib/mothership/tools/handlers/agent-cli/commands/lint.ts renamed to apps/sim/lib/mothership/agent-cli/engines/lint.ts

@@ -1,11 +1,11 @@
 import type { WorkflowState } from '@sim/workflow-types/workflow'
-import { fetchWorkflowState } from '@/lib/mothership/tools/handlers/agent-cli/commands/workflow-views'
+import { fetchWorkflowState } from '@/lib/mothership/agent-cli/engines/workflow-views'
 import {
-  type AgentCliCommand,
+  type AgentCliEngine,
   type AgentCliRuntime,
   agentCliFail,
   agentCliOk,
-} from '@/lib/mothership/tools/handlers/agent-cli/types'
+} from '@/lib/mothership/agent-cli/types'
 import { formatWorkflowLintMessage, hasWorkflowLintIssues } from '@/lib/workflows/editing/lint'
 import { buildWorkflowLintReport } from '@/lib/workflows/editing/lint-report'
 import { createEnvVarPattern } from '@/executor/utils/reference-validation'
@@ -17,10 +17,7 @@ import { createEnvVarPattern } from '@/executor/utils/reference-validation'
  * same engine both graph writes publish, so a lint here can never disagree
  * with what an edit would have reported.
  */
-export const workflowLintCommand: AgentCliCommand = {
-  path: ['workflow', 'lint'],
-  summary: 'Validate one workflow: orphans, unwired ports, missing fields, unresolved references',
-  usage: 'workflow lint <workflowId>',
+export const workflowLintCommand: AgentCliEngine = {
   async execute(rest, runtime) {
     const workflowId = rest[0]
     if (!workflowId) return agentCliFail('Usage: sim workflow lint <workflowId>')

…ols/handlers/agent-cli/commands/query.ts …ib/mothership/agent-cli/engines/query.tsapps/sim/lib/mothership/tools/handlers/agent-cli/commands/query.ts renamed to apps/sim/lib/mothership/agent-cli/engines/query.ts apps/sim/lib/mothership/tools/handlers/agent-cli/commands/query.ts renamed to apps/sim/lib/mothership/agent-cli/engines/query.ts

@@ -1,10 +1,10 @@
 import {
-  type AgentCliCommand,
+  type AgentCliEngine,
   type AgentCliFlags,
   type AgentCliRuntime,
   agentCliFail,
   agentCliOk,
-} from '@/lib/mothership/tools/handlers/agent-cli/types'
+} from '@/lib/mothership/agent-cli/types'
 import { normalizeName } from '@/executor/constants'
 
 /**
@@ -67,14 +67,11 @@ function clipValue(value: unknown): unknown {
 }
 
 function stringFlag(flags: AgentCliFlags, name: string): string | undefined {
-  const value = flags.get(name)
+  const value = flags[name]
   return typeof value === 'string' ? value : undefined
 }
 
-export const logsQueryCommand: AgentCliCommand = {
-  path: ['logs', 'query'],
-  summary: 'One row per run: a block field across run history (--block, --field, --where)',
-  usage: 'logs query <workflowId> --block <name>',
+export const logsQueryCommand: AgentCliEngine = {
   async execute(rest: string[], runtime: AgentCliRuntime, flags: AgentCliFlags) {
     const workflowId = rest[0]
     const blockName = stringFlag(flags, 'block') ?? ''