ssos-user-cli 0.2.0

package/README.md

@@ -0,0 +1,47 @@
+# ssos-user-cli
+
+创业OS（SSOS）的官方命令行工具。它使用浏览器授权登录，不在终端接收或保存邮箱密码；登录后可以从终端发现并调用当前工作区允许的 AI 业务工具。
+
+## 安装
+
+```bash
+npm install --global ssos-user-cli
+```
+
+需要 Node.js 20 或更高版本。安装完成后，命令名是 `ssos`。
+
+## 登录
+
+```bash
+ssos login
+```
+
+浏览器会打开 SSOS 登录页。用邮箱和密码登录后，按工作区名称选择要使用的工作区并授权。授权完成后回到终端即可；刷新会话保存在本机系统钥匙串中。
+
+## 查看和调用工具
+
+```bash
+ssos tools
+ssos query_bank_transactions --input '{"limit":10}'
+ssos query_vat_invoices --input '{"limit":10}'
+```
+
+先运行 `ssos tools` 查看当前工作区实际可用的工具和字段，再调用具体工具。工具权限由工作区和账号决定，CLI 不会绕过权限。
+
+## 安全说明
+
+- 邮箱密码只在 SSOS 浏览器登录页输入，不要写入命令行、脚本或环境变量。
+- CLI 使用 OAuth 2.0 + PKCE；访问令牌不会作为命令参数传递。
+- 关闭或撤销工作区授权后，再次使用请运行 `ssos login`。
+- 银行流水、发票和税务资料的最终确认仍由用户在 SSOS 中完成。
+
+## 常用命令
+
+| 命令 | 用途 |
+| --- | --- |
+| `ssos login` | 登录并选择工作区 |
+| `ssos tools` | 查看当前工作区可用工具 |
+| `ssos query_bank_transactions --input '<JSON>'` | 查询银行流水 |
+| `ssos query_vat_invoices --input '<JSON>'` | 查询增值税发票 |
+
+更多面向用户的操作说明见 [创业OS 帮助中心](https://docs.finlaw.cloud/guides/ssos-cli.html)。

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "ssos-user-cli",
+  "version": "0.2.0",
+  "description": "Official SSOS command-line client for secure workspace access and AI-assisted business tools",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xaiver03/ssos.git",
+    "directory": "tools/user-cli"
+  },
+  "homepage": "https://finlaw.cloud",
+  "bugs": {
+    "url": "https://github.com/Xaiver03/ssos/issues"
+  },
+  "keywords": [
+    "ssos",
+    "startup-os",
+    "accounting",
+    "finance",
+    "ai-tools",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "keytar": "^7.9.0"
+  },
+  "bin": {
+    "ssos": "src/index.mjs"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node --check src/index.mjs",
+    "test": "node --test test/*.test.mjs",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/auth.mjs

@@ -0,0 +1,205 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto'
+import http from 'node:http'
+import { URL } from 'node:url'
+
+const KEYCHAIN_SERVICE = 'ssos-user-cli'
+const DEFAULT_REDIRECT_PORT = 8888
+const FORBIDDEN_ENV = ['SSOS_EMAIL', 'SSOS_PASSWORD', 'SSOS_API_KEY', 'SSOS_ACCESS_TOKEN', 'STARTUPOS_PASSWORD', 'STARTUPOS_API_KEY', 'STARTUPOS_ACCESS_TOKEN']
+
+function isUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+}
+
+export function createUserCliConfig(env = process.env) {
+  if (FORBIDDEN_ENV.some(key => typeof env[key] === 'string' && env[key].trim())) {
+    throw new Error('User CLI is OAuth-only; password, API key and access-token environment variables are forbidden')
+  }
+  const workspaceId = env.SSOS_WORKSPACE_ID?.trim() || undefined
+  if (workspaceId && !isUuid(workspaceId)) throw new Error('SSOS_WORKSPACE_ID must be a UUID when supplied')
+  const requestedScopes = (env.SSOS_PERMISSION_SCOPES ?? 'accounts:view ai:use contracts:view entries:view entries:create')
+    .split(/\s+/).filter(Boolean)
+  if (requestedScopes.length === 0 || requestedScopes.some(scope => scope === 'read' || scope === 'write')) {
+    throw new Error('User CLI requires permission-point OAuth scopes')
+  }
+  return Object.freeze({
+    apiBaseUrl: env.SSOS_API_URL ?? 'https://api.finlaw.cloud',
+    appBaseUrl: env.SSOS_APP_URL ?? 'https://app.finlaw.cloud',
+    clientId: env.SSOS_OAUTH_CLIENT_ID ?? 'ssos-mcp-cli',
+    workspaceId,
+    deviceId: env.SSOS_DEVICE_ID && isUuid(env.SSOS_DEVICE_ID) ? env.SSOS_DEVICE_ID : undefined,
+    authorizationChannel: 'user_cli',
+    requestedScopes,
+    redirectPort: Number(env.SSOS_OAUTH_REDIRECT_PORT ?? DEFAULT_REDIRECT_PORT),
+  })
+}
+
+export function buildUserCliAuthorizationUrl(config) {
+  const url = new URL(`${config.appBaseUrl}/oauth/authorize`)
+  url.searchParams.set('client_id', config.clientId)
+  url.searchParams.set('redirect_uri', config.redirectUri)
+  url.searchParams.set('response_type', 'code')
+  url.searchParams.set('state', config.state)
+  url.searchParams.set('code_challenge', config.challenge)
+  url.searchParams.set('code_challenge_method', 'S256')
+  url.searchParams.set('scope', config.requestedScopes.join(' '))
+  if (config.workspaceId) url.searchParams.set('workspace_id', config.workspaceId)
+  url.searchParams.set('device_id', config.deviceId)
+  url.searchParams.set('authorization_channel', 'user_cli')
+  return url
+}
+
+function defaultKeychain() {
+  // Keep the local-agent sidecar binary free of native keychain dependencies.
+  // The OAuth cloud command loads keytar lazily only when it is actually used.
+  const keychainModule = ['key', 'tar'].join('')
+  return import(keychainModule).then(module => module.default ?? module)
+}
+
+export function createUserCliAuth(options = {}) {
+  const env = options.env ?? process.env
+  const config = createUserCliConfig(env)
+  const fetchImpl = options.fetchImpl ?? fetch
+  const clock = options.clock ?? Date.now
+  const keychainPromise = options.keychain ? Promise.resolve(options.keychain) : defaultKeychain()
+  let currentAuth = null
+  let accessToken = null
+  let expiresAt = 0
+
+  async function deviceId() {
+    if (config.deviceId) return config.deviceId
+    const keychain = await keychainPromise
+    const stored = await keychain.getPassword(KEYCHAIN_SERVICE, 'device-id')
+    if (stored && isUuid(stored)) return stored
+    const generated = randomUUID()
+    await keychain.setPassword(KEYCHAIN_SERVICE, 'device-id', generated)
+    return generated
+  }
+
+  async function persist(auth) {
+    const keychain = await keychainPromise
+    const { accessToken: _accessToken, ...refreshOnly } = auth
+    void _accessToken
+    const account = config.workspaceId ? `${auth.clientId}:${auth.workspaceId}` : `${auth.clientId}:selected`
+    await keychain.setPassword(KEYCHAIN_SERVICE, account, JSON.stringify(refreshOnly))
+  }
+
+  async function refresh() {
+    if (!currentAuth) return false
+    const response = await fetchImpl(`${config.apiBaseUrl}/api/auth/refresh`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refresh_token: currentAuth.refreshToken }),
+    })
+    if (!response.ok) return false
+    const data = await response.json()
+    const nextAccessToken = data.accessToken ?? data.access_token
+    const nextRefreshToken = data.refreshToken ?? data.refresh_token
+    if (typeof nextAccessToken !== 'string' || typeof nextRefreshToken !== 'string') return false
+    accessToken = nextAccessToken
+    expiresAt = clock() + (Number(data.expires_in ?? 900) * 1000)
+    currentAuth = { ...currentAuth, refreshToken: nextRefreshToken, expiresAt, lastUsedAt: clock() }
+    await persist(currentAuth)
+    return true
+  }
+
+  async function waitForAuthorization() {
+    const device = await deviceId()
+    const verifier = randomBytes(32).toString('base64url')
+    const challenge = createHash('sha256').update(verifier).digest('base64url')
+    const state = randomBytes(16).toString('base64url')
+    const redirectUri = `http://127.0.0.1:${config.redirectPort}/callback`
+    const authorizationUrl = buildUserCliAuthorizationUrl({ ...config, deviceId: device, redirectUri, state, challenge })
+    if (options.onAuthorizationUrl) options.onAuthorizationUrl(String(authorizationUrl))
+    else console.error(`Open this URL to authorize SSOS User CLI:\n${authorizationUrl}`)
+    const code = await new Promise((resolve, reject) => {
+      const server = http.createServer((request, response) => {
+        const url = new URL(request.url ?? '/', redirectUri)
+        if (url.pathname !== '/callback') return response.end('Not found')
+        const error = url.searchParams.get('error')
+        const codeValue = url.searchParams.get('code')
+        if (error || !codeValue || url.searchParams.get('state') !== state) {
+          response.writeHead(400); response.end('OAuth authorization failed'); server.close(); reject(new Error(error ?? 'OAuth state or code is invalid')); return
+        }
+        response.writeHead(200); response.end('SSOS authorization complete; you may close this window.'); server.close(); resolve(codeValue)
+      })
+      server.listen(config.redirectPort, '127.0.0.1')
+      const timeout = setTimeout(() => { server.close(); reject(new Error('OAuth authorization timed out')) }, 5 * 60 * 1000)
+      timeout.unref()
+    })
+    const response = await fetchImpl(`${config.apiBaseUrl}/oauth/token`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ grant_type: 'authorization_code', code, redirect_uri: redirectUri, client_id: config.clientId, code_verifier: verifier }),
+    })
+    if (!response.ok) throw new Error(`OAuth token exchange failed (${response.status})`)
+    const token = await response.json()
+    if (!token.access_token || !token.refresh_token || !token.user_id || !token.email) throw new Error('OAuth token response is incomplete')
+    accessToken = token.access_token
+    expiresAt = clock() + (Number(token.expires_in ?? 900) * 1000)
+    const selectedWorkspaceId = token.workspace_id ?? config.workspaceId
+    if (!isUuid(selectedWorkspaceId)) throw new Error('OAuth authorization did not return a selected workspace')
+    currentAuth = { method: 'oauth', userId: token.user_id, email: token.email, workspaceId: selectedWorkspaceId, workspaceName: token.workspace_name ?? undefined, clientId: config.clientId, deviceId: device, authorizationChannel: 'user_cli', scopes: token.scope?.split(/\s+/).filter(Boolean) ?? [...config.requestedScopes], refreshToken: token.refresh_token, expiresAt, savedAt: clock() }
+    await persist(currentAuth)
+  }
+
+  async function initialize() {
+    const keychain = await keychainPromise
+    const device = await deviceId()
+    const accountKey = config.workspaceId ? `${config.clientId}:${config.workspaceId}` : `${config.clientId}:selected`
+    const savedRaw = await keychain.getPassword(KEYCHAIN_SERVICE, accountKey)
+    if (savedRaw) {
+      const saved = JSON.parse(savedRaw)
+      if (saved.method === 'oauth' && saved.authorizationChannel === 'user_cli' && saved.deviceId === device) currentAuth = saved
+    }
+    if (!await refresh()) await waitForAuthorization()
+  }
+
+  async function ensureValidToken() {
+    if (!accessToken || clock() >= expiresAt - 60_000) {
+      if (!await refresh()) throw new Error('User CLI OAuth session is unavailable; run login again')
+    }
+    return accessToken
+  }
+
+  async function request(path, init = {}) {
+    const token = await ensureValidToken()
+    const workspaceId = currentAuth?.workspaceId ?? config.workspaceId
+    if (!workspaceId) throw new Error('No workspace selected; run ssos login again')
+    const response = await fetchImpl(`${config.apiBaseUrl}${path}`, {
+      ...init,
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}`, 'x-workspace-id': workspaceId, ...(init.headers ?? {}) },
+    })
+    if (!response.ok) throw new Error(`Cloud CLI request denied (${response.status})`)
+    return response.json()
+  }
+
+  return {
+    config,
+    initialize,
+    getAccessToken: async () => ensureValidToken(),
+    listTools: () => request('/api/local-agent/tools'),
+    callTool: (name, input, options = {}) => {
+      if (options.idempotencyKey !== undefined && !isUuid(options.idempotencyKey)) {
+        throw new Error('idempotencyKey must be a UUID')
+      }
+      return request(`/api/local-agent/tools/${encodeURIComponent(name)}/invoke`, {
+        method: 'POST',
+        body: JSON.stringify({
+          arguments: input,
+          ...(options.idempotencyKey ? { idempotency_key: options.idempotencyKey } : {}),
+        }),
+      })
+    },
+    confirmActionPlan: (planId) => {
+      if (!isUuid(planId)) throw new Error('Action Plan id must be a UUID')
+      return request(`/api/local-agent/action-plans/${encodeURIComponent(planId)}/confirm`, {
+        method: 'POST', body: '{}',
+      })
+    },
+    cancelActionPlan: (planId) => {
+      if (!isUuid(planId)) throw new Error('Action Plan id must be a UUID')
+      return request(`/api/local-agent/action-plans/${encodeURIComponent(planId)}/cancel`, {
+        method: 'POST', body: '{}',
+      })
+    },
+  }
+}

package/src/canonical-manifest.mjs

@@ -0,0 +1,41 @@
+const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/
+
+function assertToolDefinition(tool, index) {
+  if (!tool || typeof tool !== 'object') {
+    throw new Error(`Canonical tool ${index} is invalid`)
+  }
+  if (typeof tool.name !== 'string' || !TOOL_NAME_PATTERN.test(tool.name)) {
+    throw new Error(`Canonical tool ${index} has an invalid name`)
+  }
+  if (tool.description !== undefined && typeof tool.description !== 'string') {
+    throw new Error(`Canonical tool ${tool.name} has an invalid description`)
+  }
+  if (tool.input_schema !== undefined && (typeof tool.input_schema !== 'object' || tool.input_schema === null)) {
+    throw new Error(`Canonical tool ${tool.name} has an invalid input schema`)
+  }
+}
+
+/**
+ * Project the cloud canonical Manifest into a local command index.
+ *
+ * This projection intentionally drops permission/role claims. The local CLI
+ * may display a command and validate its input shape, but only the cloud
+ * user_cli boundary can authorize or invoke it.
+ */
+export function projectCanonicalCommands(tools) {
+  if (!Array.isArray(tools)) throw new Error('Canonical discovery must return a tools array')
+
+  return Object.freeze(tools.map((tool, index) => {
+    assertToolDefinition(tool, index)
+    return Object.freeze({
+      name: tool.name,
+      description: tool.description ?? '',
+      inputSchema: tool.input_schema ?? {},
+      annotations: tool.annotations ?? {},
+    })
+  }))
+}
+
+export function findCanonicalCommand(commands, name) {
+  return commands.find(command => command.name === name)
+}

package/src/index.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url'
+import { projectCanonicalCommands } from './canonical-manifest.mjs'
+import { findCanonicalCommand } from './canonical-manifest.mjs'
+import { createUserCliAuth } from './auth.mjs'
+import { runLocalAgentCommand } from './local-agent-command.mjs'
+import {
+  LOCAL_CLI_COMMANDS,
+  findLocalCliCommand,
+  parseLocalCliInput,
+  projectLocalCliCommands,
+} from './local-command-manifest.mjs'
+
+/** Static protocol metadata. Authorization and execution are never decided here. */
+export const USER_CLI_COMMANDS = LOCAL_CLI_COMMANDS
+
+export function createUserCliCommandIndex(tools) {
+  return projectCanonicalCommands(tools)
+}
+
+export function createLocalCliCommandIndex(commandIds = LOCAL_CLI_COMMANDS.map(({ id }) => id)) {
+  return projectLocalCliCommands(commandIds)
+}
+
+function printHelp(output) {
+  output.stdout('SSOS User CLI')
+  output.stdout('Cloud commands: ssos <command> --input \'<json>\'')
+  output.stdout('Cloud login: ssos login (browser login + named workspace selection)')
+  output.stdout('Local Desktop commands: ssos local tools')
+  output.stdout('Local Desktop run: ssos local <command_id> --cwd <directory> --input \'<json>\'')
+  output.stdout('Local Agent auth: ssos local-agent token')
+  output.stdout('Action Plan: ssos action-plan <confirm|cancel> <plan-id>')
+  output.stdout('Local Agent business tools: ssos local-agent invoke --tool <id> --input \'<json>\' [--idempotency-key <uuid>]')
+  output.stdout('MCP is optional; it is not required for the CLI or Desktop local runner.')
+}
+
+function parseFlag(argv, name) {
+  const index = argv.indexOf(name)
+  return index >= 0 ? argv[index + 1] : undefined
+}
+
+async function runLocalCommand(argv, options, output) {
+  const commandIds = options.localCommandIds ?? LOCAL_CLI_COMMANDS.map(({ id }) => id)
+  const commands = createLocalCliCommandIndex(commandIds)
+  if (argv[1] === 'tools' || argv.length === 1) {
+    output.stdout(JSON.stringify(commands, null, 2))
+    return 0
+  }
+
+  const command = findLocalCliCommand(argv[1])
+  if (!command || !commands.some(({ id }) => id === command.id)) {
+    output.stderr('Local command unavailable: it is not in the Desktop capability catalog.')
+    return 2
+  }
+  if (typeof options.localRunner !== 'function') {
+    output.stderr('Local runner unavailable: run this command from SSOS Desktop or provide a bridge.')
+    return 3
+  }
+
+  const cwd = parseFlag(argv, '--cwd')
+  if (!cwd) {
+    output.stderr('Local command requires --cwd <approved-directory>.')
+    return 2
+  }
+  const result = await options.localRunner({
+    commandId: command.id,
+    cwd,
+    confirmed: options.confirmed === true,
+    timeoutMs: options.timeoutMs,
+    outputLimitBytes: options.outputLimitBytes,
+    input: parseLocalCliInput(parseFlag(argv, '--input')),
+  })
+  output.stdout(JSON.stringify(result, null, 2))
+  return 0
+}
+
+export async function runUserCliAsync(argv, options = {}) {
+  const output = options.output ?? { stdout: console.log, stderr: console.error }
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    printHelp(output)
+    return 0
+  }
+
+  if (argv[0] === 'local') {
+    return runLocalCommand(argv, options, output)
+  }
+
+  if (argv[0] === 'local-agent') {
+    return runLocalAgentCommand(argv.slice(1), {
+      env: options.env,
+      fetchImpl: options.fetchImpl,
+      client: options.localAgentClient,
+      auth: options.auth,
+      onAuthorizationUrl: options.onAuthorizationUrl,
+    }, output)
+  }
+
+  const auth = options.auth ?? createUserCliAuth()
+  await auth.initialize()
+
+  if (argv[0] === 'login') {
+    output.stdout('SSOS 登录完成；工作区已在浏览器授权页按名称选择并保存。')
+    return 0
+  }
+
+  if (argv[0] === 'action-plan') {
+    const action = argv[1]
+    const planId = argv[2]
+    if ((action !== 'confirm' && action !== 'cancel') || !planId || argv.length !== 3) {
+      output.stderr('Usage: ssos action-plan <confirm|cancel> <plan-id>')
+      return 2
+    }
+    const result = action === 'confirm'
+      ? await auth.confirmActionPlan(planId)
+      : await auth.cancelActionPlan(planId)
+    output.stdout(JSON.stringify(result, null, 2))
+    return 0
+  }
+
+  const discovered = await auth.listTools()
+  const commands = createUserCliCommandIndex(discovered.tools ?? [])
+
+  if (argv[0] === 'tools') {
+    output.stdout(JSON.stringify(commands, null, 2))
+    return 0
+  }
+
+  const command = findCanonicalCommand(commands, argv[0])
+  if (!command) {
+    output.stderr('Command unavailable: it is not present in the trusted cloud Manifest.')
+    return 2
+  }
+
+  const inputIndex = argv.indexOf('--input')
+  const input = inputIndex >= 0 ? JSON.parse(argv[inputIndex + 1] ?? '{}') : {}
+  const idempotencyKey = parseFlag(argv, '--idempotency-key')
+  const result = await auth.callTool(command.name, input, { idempotencyKey })
+  output.stdout(JSON.stringify(result, null, 2))
+  return 0
+}
+
+export function runUserCli(
+  argv,
+  output = { stdout: console.log, stderr: console.error },
+) {
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    printHelp(output)
+    return 0
+  }
+
+  output.stderr('Command unavailable: the user CLI is fail-closed during secure channel rollout.')
+  return 2
+}
+
+const invokedPath = process.argv[1]
+if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
+  runUserCliAsync(process.argv.slice(2)).then((code) => { process.exitCode = code }).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  })
+}

package/src/local-agent-command.mjs

@@ -0,0 +1,142 @@
+import { URL } from 'node:url'
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+const MAX_INPUT_BYTES = 64 * 1024
+const MAX_OUTPUT_BYTES = 512 * 1024
+
+function isUuid(value) {
+  return typeof value === 'string' && UUID_PATTERN.test(value)
+}
+
+function parseFlag(argv, name) {
+  const index = argv.indexOf(name)
+  return index >= 0 ? argv[index + 1] : undefined
+}
+
+function parseJsonInput(raw) {
+  if (!raw) return {}
+  const bytes = Buffer.byteLength(raw, 'utf8')
+  if (bytes > MAX_INPUT_BYTES) throw new Error(`Input exceeds ${MAX_INPUT_BYTES} bytes`)
+  const value = JSON.parse(raw)
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Input must be a JSON object')
+  return value
+}
+
+function createTokenClient(env, fetchImpl = fetch) {
+  const token = typeof env.SSOS_LOCAL_AGENT_TOKEN === 'string' ? env.SSOS_LOCAL_AGENT_TOKEN.trim() : ''
+  const workspaceId = env.SSOS_WORKSPACE_ID ?? ''
+  if (!token) throw new Error('SSOS_LOCAL_AGENT_TOKEN is required for local-agent commands')
+  if (!isUuid(workspaceId)) throw new Error('SSOS_WORKSPACE_ID must be a UUID')
+  const baseUrl = (env.SSOS_API_URL ?? 'https://api.finlaw.cloud').replace(/\/$/, '')
+  return async (path, init = {}) => {
+    const response = await fetchImpl(new URL(path, `${baseUrl}/`), {
+      ...init,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+        'x-workspace-id': workspaceId,
+        ...(init.headers ?? {}),
+      },
+    })
+    const text = await response.text()
+    if (Buffer.byteLength(text, 'utf8') > MAX_OUTPUT_BYTES) throw new Error(`Response exceeds ${MAX_OUTPUT_BYTES} bytes`)
+    let body = {}
+    if (text) {
+      try { body = JSON.parse(text) } catch { body = { content: [{ type: 'text', text }] } }
+    }
+    if (!response.ok) {
+      const error = new Error(`Local-agent request denied (${response.status})`)
+      error.status = response.status
+      error.body = body
+      throw error
+    }
+    return body
+  }
+}
+
+export function createLocalAgentClient(options = {}) {
+  return createTokenClient(options.env ?? process.env, options.fetchImpl ?? fetch)
+}
+
+export async function runLocalAgentCommand(argv, options = {}, output = { stdout: console.log, stderr: console.error }) {
+  if (argv[0] === 'token') {
+    if (argv.length > 1) {
+      output.stderr('Usage: ssos local-agent token')
+      return 2
+    }
+    const auth = options.auth ?? (await import('./auth.mjs')).createUserCliAuth({
+      env: options.env ?? process.env,
+      fetchImpl: options.fetchImpl ?? fetch,
+      onAuthorizationUrl: options.onAuthorizationUrl,
+    })
+    await auth.initialize()
+    const token = await auth.getAccessToken()
+    output.stdout(JSON.stringify({ access_token: token }))
+    return 0
+  }
+  const client = options.client ?? createLocalAgentClient({ env: options.env ?? process.env, fetchImpl: options.fetchImpl ?? fetch })
+  if (argv.length === 0 || argv[0] === 'tools') {
+    output.stdout(JSON.stringify(await client('/api/local-agent/tools'), null, 2))
+    return 0
+  }
+  if (argv[0] === 'action-plan') {
+    const action = argv[1]
+    const planId = argv[2]
+    if ((action !== 'confirm' && action !== 'cancel') || !isUuid(planId) || argv.length !== 3) {
+      output.stderr('Usage: ssos local-agent action-plan <confirm|cancel> <plan-id>')
+      return 2
+    }
+    try {
+      const result = await client(`/api/local-agent/action-plans/${encodeURIComponent(planId)}/${action}`, {
+        method: 'POST', body: '{}',
+      })
+      output.stdout(JSON.stringify(result, null, 2))
+      return 0
+    } catch (error) {
+      const status = Number(error?.status)
+      if (status === 401 || status === 403) output.stderr('Local-agent request denied by server policy.')
+      else output.stderr(error instanceof Error ? error.message : String(error))
+      return status === 401 || status === 403 ? 4 : 5
+    }
+  }
+  if (argv[0] !== 'invoke') {
+    output.stderr('Usage: ssos local-agent tools | ssos local-agent invoke --tool <id> --input \'<json>\' [--idempotency-key <uuid>] | ssos local-agent action-plan <confirm|cancel> <plan-id>')
+    return 2
+  }
+  const toolName = parseFlag(argv, '--tool')
+  if (!toolName || !/^[a-z][a-z0-9_-]{1,127}$/i.test(toolName)) {
+    output.stderr('local-agent invoke requires a valid --tool <id>.')
+    return 2
+  }
+  let input
+  try {
+    input = parseJsonInput(parseFlag(argv, '--input'))
+  } catch (error) {
+    output.stderr(error instanceof Error ? error.message : String(error))
+    return 2
+  }
+  const idempotencyKey = parseFlag(argv, '--idempotency-key')
+  if (idempotencyKey !== undefined && !isUuid(idempotencyKey)) {
+    output.stderr('local-agent invoke requires --idempotency-key to be a UUID.')
+    return 2
+  }
+  try {
+    const result = await client(`/api/local-agent/tools/${encodeURIComponent(toolName)}/invoke`, {
+      method: 'POST',
+      body: JSON.stringify({
+        arguments: input,
+        ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
+      }),
+    })
+    output.stdout(JSON.stringify(result, null, 2))
+    return 0
+  } catch (error) {
+    const status = Number(error?.status)
+    if (status === 401 || status === 403) output.stderr('Local-agent request denied by server policy.')
+    else output.stderr(error instanceof Error ? error.message : String(error))
+    return status === 401 || status === 403 ? 4 : 5
+  }
+}
+
+export const LOCAL_AGENT_LIMITS = Object.freeze({ MAX_INPUT_BYTES, MAX_OUTPUT_BYTES })

package/src/local-command-manifest.mjs

@@ -0,0 +1,67 @@
+const COMMAND_ID_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/
+
+/**
+ * The local command catalog is a protocol description, not an authorization
+ * table. Execution remains in the Desktop bridge, where the workspace policy
+ * and one-time confirmation are enforced by Rust.
+ */
+export const LOCAL_CLI_COMMANDS = Object.freeze([
+  {
+    id: 'git_status',
+    description: 'Show the working tree status',
+    capability: 'execute',
+    inputSchema: { type: 'object', additionalProperties: false },
+  },
+  {
+    id: 'git_diff',
+    description: 'Show a compact working tree diff summary',
+    capability: 'execute',
+    inputSchema: { type: 'object', additionalProperties: false },
+  },
+  {
+    id: 'rg_files',
+    description: 'List files in the approved workspace',
+    capability: 'execute',
+    inputSchema: { type: 'object', additionalProperties: false },
+  },
+  {
+    id: 'npm_test',
+    description: 'Run the workspace test command',
+    capability: 'execute',
+    inputSchema: { type: 'object', additionalProperties: false },
+  },
+  {
+    id: 'npm_build',
+    description: 'Run the workspace production build',
+    capability: 'execute',
+    inputSchema: { type: 'object', additionalProperties: false },
+  },
+].map((command) => Object.freeze(command)))
+
+const COMMANDS_BY_ID = new Map(LOCAL_CLI_COMMANDS.map((command) => [command.id, command]))
+
+export function projectLocalCliCommands(commandIds) {
+  if (!Array.isArray(commandIds)) throw new Error('Local command discovery must return an array')
+
+  return Object.freeze(commandIds.map((id, index) => {
+    if (typeof id !== 'string' || !COMMAND_ID_PATTERN.test(id)) {
+      throw new Error(`Local command ${index} has an invalid id`)
+    }
+    const command = COMMANDS_BY_ID.get(id)
+    if (!command) throw new Error(`Local command is not registered: ${id}`)
+    return command
+  }))
+}
+
+export function findLocalCliCommand(commandId) {
+  return COMMANDS_BY_ID.get(commandId)
+}
+
+export function parseLocalCliInput(raw) {
+  if (raw === undefined) return {}
+  const input = JSON.parse(raw)
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new Error('Local CLI input must be a JSON object')
+  }
+  return input
+}