@ducking-mind/proxy-app-cli 0.1.0 → 0.1.1

package/agent-runtime/protocol.mjs

@@ -0,0 +1,325 @@
+/**
+ * Shared protocol primitives for exposing Proxy Desktop applications to an
+ * external agent (for example, through MCP). This module has no Electron or
+ * transport dependency and is safe to use from the desktop host and tests.
+ */
+
+import { serializeAgentError } from './runtime-status.mjs'
+import { createHash } from 'node:crypto'
+
+export const AGENT_PROTOCOL = 'proxy.desktop.agent/v1'
+export const AGENT_PROTOCOL_VERSION = 1
+
+export const ACCESS = Object.freeze({ READ: 'read', WRITE: 'write' })
+
+const LEGACY_APP_ID_RE = /^app-[a-z0-9][a-z0-9._-]{0,119}$/
+const PLATFORM_APP_ID_RE = /^app_[a-z0-9][a-z0-9._-]{2,119}$/
+const VERSION_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/
+const NAMESPACE_RE = /^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$/
+const CAPABILITY_RE = /^[a-z][a-z0-9]*(?:[_-][a-z0-9]+)*$/
+const TOOL_RE = /^proxy_[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/
+const AGENT_TARGETS = Object.freeze(['web', 'desktop'])
+const MAX_SCHEMA_BYTES = 64 * 1024
+const RESERVED_NAMESPACES = new Set(['app', 'codex', 'desktop', 'proxy', 'system'])
+
+export function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function assert(condition, message) {
+  if (!condition) throw new TypeError(message)
+}
+
+export function isPublicAppSlug(value) {
+  return typeof value === 'string' && value === value.trim() && value.length <= 120 && /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/.test(value)
+}
+
+export function isAppManifestID(value) {
+  return isPublicAppSlug(value) || (typeof value === 'string' && value === value.trim() && PLATFORM_APP_ID_RE.test(value))
+}
+
+// Only metadata from the authenticated platform (or the trusted account
+// broker) may approve a historical manifest identity. Never infer an alias by
+// adding/removing a prefix, and never alias one stable platform ID to another.
+export function appManifestIdentityMatches(value, metadata) {
+  if (!isAppManifestID(value) || !metadata) return false
+  const id = metadata.app_id || metadata.id
+  if (PLATFORM_APP_ID_RE.test(value)) return value === id
+  if (value === (metadata.app_slug || metadata.slug)) return true
+  return Array.isArray(metadata.app_aliases) && metadata.app_aliases.some(alias => isPublicAppSlug(alias) && alias === value)
+}
+
+export function assertAppId(value) {
+  assert(isAppManifestID(value) || (typeof value === 'string' && value === value.trim() && LEGACY_APP_ID_RE.test(value)), `invalid app id: ${value}`)
+  return value
+}
+
+export function assertVersion(value) {
+  assert(typeof value === 'string' && VERSION_RE.test(value), `invalid app version: ${value}`)
+  return value
+}
+
+export function assertNamespace(value) {
+  assert(typeof value === 'string' && NAMESPACE_RE.test(value) && value.length <= 48,
+    `invalid agent namespace: ${value}`)
+  return value
+}
+
+export function assertCapabilityName(value) {
+  assert(typeof value === 'string' && CAPABILITY_RE.test(value) && value.length <= 64,
+    `invalid capability name: ${value}`)
+  return value
+}
+
+export function normalizeAgentTargets(value, field = 'targets', fallback = ['desktop']) {
+  const targets = value === undefined ? fallback : value
+  assert(Array.isArray(targets) && targets.length > 0 && targets.length <= AGENT_TARGETS.length, `${field} must list one or more targets`)
+  assert(new Set(targets).size === targets.length && targets.every(target => AGENT_TARGETS.includes(target)), `${field} must contain only web or desktop`)
+  return Object.freeze(AGENT_TARGETS.filter(target => targets.includes(target)))
+}
+
+export function normalizeSchema(value, field = 'schema') {
+  const schema = value === undefined ? { type: 'object' } : value
+  assert(isRecord(schema), `${field} must be a JSON schema object`)
+  let bytes
+  try { bytes = Buffer.byteLength(JSON.stringify(schema)) } catch { bytes = Infinity }
+  assert(bytes <= MAX_SCHEMA_BYTES, `${field} exceeds ${MAX_SCHEMA_BYTES} bytes`)
+  validateSchema(schema, field)
+  return schema
+}
+
+export function normalizeCapabilityDeclaration(input, { defaultTargets = ['desktop'] } = {}) {
+  assert(isRecord(input), 'agent capability must be an object')
+  const name = assertCapabilityName(input.name)
+  const description = input.description === undefined ? '' : input.description
+  assert(typeof description === 'string' && description.length <= 2048, `invalid description for ${name}`)
+  const access = input.access === undefined ? ACCESS.READ : input.access
+  assert(access === ACCESS.READ || access === ACCESS.WRITE, `invalid access for ${name}`)
+  const idempotent = input.idempotent === undefined ? access === ACCESS.READ : input.idempotent
+  assert(typeof idempotent === 'boolean', `invalid idempotent value for ${name}`)
+  const title = input.title === undefined ? name : input.title
+  assert(typeof title === 'string' && title.length <= 200, `invalid title for ${name}`)
+  for (const field of ['destructive', 'open_world', 'billable']) if (input[field] !== undefined) assert(typeof input[field] === 'boolean', `invalid ${field} for ${name}`)
+  const completion = input.completion || 'completed'
+  assert(['completed', 'accepted'].includes(completion), `invalid completion for ${name}`)
+  const targets = normalizeAgentTargets(input.targets, `${name}.targets`, defaultTargets)
+  const inputSchema = normalizeSchema(input.input_schema ?? input.inputSchema, `${name}.input_schema`)
+  const outputSchema = normalizeSchema(input.output_schema ?? input.outputSchema, `${name}.output_schema`)
+  assert(inputSchema.type === 'object' && outputSchema.type === 'object', 'tool schemas must have object roots')
+  if (access === ACCESS.WRITE) assert(inputSchema.properties?.idempotency_key?.type === 'string' && inputSchema.required?.includes('idempotency_key'), 'write capabilities must require a string idempotency_key')
+  return Object.freeze({
+    name,
+    title,
+    description,
+    destructive: input.destructive ?? access === ACCESS.WRITE,
+    open_world: input.open_world ?? false,
+    billable: input.billable ?? false,
+    completion,
+    targets,
+    access,
+    idempotent,
+    input_schema: inputSchema,
+    output_schema: outputSchema,
+  })
+}
+
+export function normalizeManifestAgent(manifest) {
+  assert(isRecord(manifest), 'manifest must be an object')
+  const agent = manifest.agent
+  if (agent === undefined) return null
+  assert(isRecord(agent), 'manifest.agent must be an object')
+  if (agent.enabled === false) return null
+  assert(agent.enabled === true, 'manifest.agent.enabled must be true or false')
+  if (agent.contract_source !== undefined) assert(agent.contract_source === 'code', 'invalid agent contract_source')
+  assert(!(agent.contract_source === 'code' && agent.entry), 'generated code contract must not retain agent.entry')
+  assert(!(agent.entry && agent.capabilities !== undefined), 'agent.entry and agent.capabilities cannot both be present')
+  assertAppId(manifest.id)
+  assertVersion(manifest.version)
+  const namespace = assertNamespace(agent.namespace || manifest.id.replace(/^app\./, '').replace(/[^a-zA-Z0-9]+/g, '_').toLowerCase())
+  assert(!RESERVED_NAMESPACES.has(namespace), `reserved agent namespace: ${namespace}`)
+  const targets = normalizeAgentTargets(agent.targets, 'manifest.agent.targets')
+  // Source projects reference their capability module. Packaged code-first
+  // apps carry its generated declarations for discovery before launch.
+  const raw = agent.capabilities === undefined ? [] : agent.capabilities
+  assert(Array.isArray(raw) && raw.length <= 64, 'manifest.agent.capabilities must be an array with at most 64 entries')
+  const capabilities = raw.map(capability => normalizeCapabilityDeclaration(capability, { defaultTargets: targets }))
+  const seen = new Set()
+  for (const capability of capabilities) {
+    assert(capability.targets.every(target => targets.includes(target)), `${capability.name}.targets must be a subset of manifest.agent.targets`)
+    assert(!seen.has(capability.name), `duplicate agent capability: ${capability.name}`)
+    seen.add(capability.name)
+  }
+  const tools = capabilities.map(capability => toolNameFor(namespace, capability.name))
+  assert(new Set(tools).size === tools.length, 'duplicate generated tool name')
+  const contractVersion = assertVersion(agent.contract_version || manifest.version)
+  const summary = agent.summary || manifest.description || ''
+  assert(typeof summary === 'string' && summary.length <= 2048, 'invalid agent summary')
+  const keywords = agent.keywords || []
+  assert(Array.isArray(keywords) && keywords.length <= 24 && keywords.every(item => typeof item === 'string' && item.length > 0 && item.length <= 80), 'invalid agent keywords')
+  if (agent.guide !== undefined) {
+    assert(isRecord(agent.guide) && typeof agent.guide.entry === 'string', 'invalid agent guide')
+    assert(Array.isArray(agent.guide.topics || []) && (agent.guide.topics || []).length <= 16, 'invalid agent guide topics')
+  }
+  if (agent.examples !== undefined) assert(typeof agent.examples === 'string', 'invalid agent examples')
+  return Object.freeze({ enabled: true, namespace, targets, contractVersion, summary, keywords, guide: agent.guide, examples: agent.examples, capabilities })
+}
+
+const canonical = value => Array.isArray(value) ? value.map(canonical) : isRecord(value) ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value
+/** Same contract identity for market metadata and installed packages, independent of transport/runtime state. */
+export function describeAgentContract(manifest) {
+  const agent = normalizeManifestAgent(manifest)
+  if (!agent) return null
+  const contract = { appId: manifest.id, namespace: agent.namespace, contractVersion: agent.contractVersion, targets: agent.targets,
+    capabilities: [...agent.capabilities].sort((a, b) => a.name.localeCompare(b.name)) }
+  return { enabled: true, namespace: agent.namespace, targets: agent.targets, contractVersion: agent.contractVersion,
+    contractHash: createHash('sha256').update(JSON.stringify(canonical(contract))).digest('hex'),
+    capabilityCount: agent.capabilities.length,
+    desktopCapabilityCount: agent.capabilities.filter(capability => capability.targets.includes('desktop')).length,
+    webCapabilityCount: agent.capabilities.filter(capability => capability.targets.includes('web')).length,
+    capabilities: agent.capabilities.map(({ name, title, description, access, targets, billable, completion }) => ({ name, title, description, access, targets, billable, completion })) }
+}
+
+export function normalizeRuntimeCapability(input) {
+  assert(isRecord(input), 'runtime capability must be an object')
+  const name = assertCapabilityName(input.name)
+  if (input.handlerVersion !== undefined) {
+    assert(Number.isInteger(input.handlerVersion) && input.handlerVersion > 0, `invalid handlerVersion for ${name}`)
+  }
+  if (input.available !== undefined) assert(typeof input.available === 'boolean', `invalid available for ${name}`)
+  return Object.freeze({ name, handlerVersion: input.handlerVersion || 1, available: input.available !== false })
+}
+
+export function validateRuntimeRegistration(manifest, registration, { target = 'desktop' } = {}) {
+  assert(AGENT_TARGETS.includes(target), 'invalid runtime target')
+  assert(isRecord(registration), 'runtime registration must be an object')
+  const agent = normalizeManifestAgent(manifest)
+  assert(agent, 'agent capabilities are not enabled in manifest')
+  assertAppId(registration.appId)
+  assertVersion(registration.version)
+  assert(registration.appId === manifest.id, 'runtime app id does not match manifest')
+  assert(registration.version === manifest.version, 'runtime app version does not match manifest')
+  assert(Array.isArray(registration.capabilities) && registration.capabilities.length <= 64, 'runtime capabilities must be an array with at most 64 entries')
+  const codeFirst = manifest.agent.contract_source === 'code'
+  const dynamic = registration.dynamic === true && !codeFirst
+  const declarations = new Map(agent.capabilities.map((capability) => [capability.name, capability]))
+  const runtime = []
+  const registeredDeclarations = []
+  const seen = new Set()
+  for (const raw of registration.capabilities) {
+    const capability = normalizeRuntimeCapability(raw)
+    assert(!seen.has(capability.name), `duplicate runtime capability: ${capability.name}`)
+    seen.add(capability.name)
+    let declared = declarations.get(capability.name)
+    const hasContract = ['title', 'description', 'access', 'input_schema', 'inputSchema', 'output_schema', 'outputSchema', 'targets', 'completion', 'idempotent', 'destructive', 'open_world', 'billable'].some(field => Object.hasOwn(raw, field))
+    let supplied
+    if (codeFirst || dynamic || hasContract) {
+      if (codeFirst || dynamic) assert(raw.access !== undefined && (raw.input_schema ?? raw.inputSchema) !== undefined && (raw.output_schema ?? raw.outputSchema) !== undefined, `runtime capability requires a complete code declaration: ${capability.name}`)
+      supplied = normalizeCapabilityDeclaration(raw, { defaultTargets: agent.targets })
+      assert(supplied.targets.every(item => agent.targets.includes(item)), `${capability.name}.targets must be a subset of application targets`)
+      assert(supplied.targets.includes(target), `runtime capability does not support ${target}: ${capability.name}`)
+    }
+    // Code-first applications provide the complete contract at runtime. The
+    // names-only form remains a compatibility path for already packaged
+    // applications whose generated manifest contains the contract.
+    if (declared) {
+      assert(declared.targets.includes(target), `runtime capability does not support ${target}: ${capability.name}`)
+      if (codeFirst) {
+        assert(JSON.stringify(canonical(supplied)) === JSON.stringify(canonical(declared)), `runtime capability contract differs from packaged code contract: ${capability.name}`)
+      }
+    } else if (!dynamic) {
+      assert(false, `runtime capability is not declared: ${capability.name}`)
+    }
+    if (dynamic) {
+      declared = supplied
+      declarations.set(capability.name, declared)
+    }
+    registeredDeclarations.push(declared)
+    if (capability.available) runtime.push({ ...capability, declaration: declared })
+  }
+  return Object.freeze({
+    appId: registration.appId,
+    version: registration.version,
+    capabilities: runtime,
+    declarations: registeredDeclarations,
+  })
+}
+
+export function toolNameFor(namespace, capability) {
+  assertNamespace(namespace)
+  assertCapabilityName(capability)
+  const name = `proxy_${namespace.replaceAll('-', '_').replaceAll('.', '_')}_${capability.replaceAll('-', '_')}`
+  assert(name.length <= 128 && TOOL_RE.test(name), `invalid generated tool name: ${name}`)
+  return name
+}
+
+export function toMcpTool({ namespace, appId, version, contractVersion = version, contractHash, capability, runtime }) {
+  const declaration = normalizeCapabilityDeclaration({ ...capability, name: capability.name })
+  const tool = {
+    name: toolNameFor(namespace, declaration.name),
+    title: declaration.title,
+    description: [declaration.description || `${appId} ${declaration.name}`, declaration.billable ? 'May incur model or service charges.' : '', declaration.completion === 'accepted' ? 'Returns acceptance only; use the application task query to check completion.' : ''].filter(Boolean).join(' '),
+    inputSchema: declaration.input_schema,
+    _meta: { proxy: { appId, version, contractVersion, ...(contractHash ? { contractHash } : {}), capability: declaration.name, billable: declaration.billable, completion: declaration.completion, targets: declaration.targets } },
+  }
+  if (declaration.output_schema) tool.outputSchema = declaration.output_schema
+  tool.annotations = { readOnlyHint: declaration.access === ACCESS.READ, destructiveHint: declaration.destructive, idempotentHint: declaration.idempotent, openWorldHint: declaration.open_world }
+  if (runtime) tool._meta.proxy.runtime = runtime
+  return Object.freeze(tool)
+}
+
+export function createInvocation({ requestId, appId, appVersion, capability, args, deadlineAt, cancellationToken }) {
+  assert(typeof requestId === 'string' && requestId.length > 0 && requestId.length <= 128, 'invalid request id')
+  assertAppId(appId); assertVersion(appVersion); assertCapabilityName(capability)
+  assert(args === undefined || isRecord(args), 'agent arguments must be an object')
+  return Object.freeze({ requestId, appId, appVersion, capability, args: args || {}, deadlineAt, cancellationToken })
+}
+
+export function serializeError(error) {
+  return serializeAgentError(error)
+}
+
+
+// Deliberately bounded JSON Schema subset. Reject unsupported keywords instead
+// of advertising validation that the host cannot actually enforce.
+const keywords = new Set(['type', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'minLength', 'maxLength', 'minimum', 'maximum', 'minItems', 'maxItems', 'description', 'title', 'default'])
+export function validateSchema(schema, path = '$', depth = 0) {
+  assert(depth <= 16 && isRecord(schema), `${path}: invalid or too deeply nested schema`)
+  for (const key of Object.keys(schema)) assert(keywords.has(key), `${path}: unsupported schema keyword ${key}`)
+  const allowed = ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type]
+  assert(types.every(type => allowed.includes(type)) && (types.length === 1 || types.length === 2 && new Set(types).size === 2 && types.includes('null')), `${path}: explicit type or a nullable type pair is required`)
+  const type = types.find(type => type !== 'null') || 'null'
+  if (schema.properties !== undefined) {
+    assert(type === 'object' && isRecord(schema.properties), `${path}: invalid properties`)
+    for (const [key, value] of Object.entries(schema.properties)) validateSchema(value, `${path}.${key}`, depth + 1)
+  }
+  if (schema.required !== undefined) assert(Array.isArray(schema.required) && schema.required.every(key => typeof key === 'string' && Object.hasOwn(schema.properties || {}, key)), `${path}: invalid required fields`)
+  if (schema.additionalProperties !== undefined) assert(typeof schema.additionalProperties === 'boolean', `${path}: additionalProperties must be boolean`)
+  if (type === 'array') validateSchema(schema.items, `${path}[]`, depth + 1)
+  if (schema.enum !== undefined) assert(Array.isArray(schema.enum) && schema.enum.length > 0, `${path}: invalid enum`)
+  for (const key of ['minimum', 'maximum', 'minLength', 'maxLength', 'minItems', 'maxItems']) if (schema[key] !== undefined) {
+    assert(Number.isFinite(schema[key]), `${path}: invalid ${key}`)
+    if (!['minimum', 'maximum'].includes(key)) assert(Number.isInteger(schema[key]) && schema[key] >= 0, `${path}: invalid ${key}`)
+  }
+}
+export function validateValue(schema, value, path = '$') {
+  const fail = (message) => { throw Object.assign(new Error(`${path}: ${message}`), { code: 'AGENT_INVALID_ARGUMENT' }) }
+  const types = Array.isArray(schema.type) ? schema.type : [schema.type]
+  const type = value === null && types.includes('null') ? 'null' : types.find(type => type !== 'null') || 'null'
+  const valid = type === 'object' ? isRecord(value) : type === 'array' ? Array.isArray(value) : type === 'null' ? value === null : type === 'integer' ? Number.isInteger(value) : typeof value === type
+  if (!valid || (typeof value === 'number' && !Number.isFinite(value))) fail(`expected ${type}`)
+  if (schema.enum && !schema.enum.some(item => JSON.stringify(item) === JSON.stringify(value))) fail('value is not in enum')
+  if (type === 'object') {
+    for (const key of schema.required || []) if (!Object.hasOwn(value, key)) fail(`missing ${key}`)
+    for (const [key, item] of Object.entries(value)) {
+      if (Object.hasOwn(schema.properties || {}, key)) validateValue(schema.properties[key], item, `${path}.${key}`)
+      else if (schema.additionalProperties === false) fail(`unknown field ${key}`)
+    }
+  }
+  if (type === 'array') {
+    if (schema.minItems !== undefined && value.length < schema.minItems || schema.maxItems !== undefined && value.length > schema.maxItems) fail('array length out of range')
+    value.forEach((item, i) => validateValue(schema.items, item, `${path}[${i}]`))
+  }
+  if (type === 'string' && (schema.minLength !== undefined && value.length < schema.minLength || schema.maxLength !== undefined && value.length > schema.maxLength)) fail('string length out of range')
+  if (typeof value === 'number' && (schema.minimum !== undefined && value < schema.minimum || schema.maximum !== undefined && value > schema.maximum)) fail('number out of range')
+}

package/agent-runtime/runtime-status.mjs

@@ -0,0 +1,70 @@
+/** Descriptive renderer state only; neither status nor recovery hints grant access. */
+const states = new Set(['ready', 'auth_required', 'loading', 'no_document', 'busy', 'error'])
+const actions = new Set(['wait', 'user_login', 'open_document', 'retry', 'inspect_state'])
+const record = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const check = (condition, message) => { if (!condition) throw new TypeError(message) }
+const keys = (value, allowed, field) => check(Object.keys(value).every(key => allowed.includes(key)), `Unexpected ${field} field`)
+
+export function normalizeNextAction(value) {
+  check(record(value), 'nextAction must be an object')
+  keys(value, ['type', 'capability'], 'nextAction')
+  check(actions.has(value.type), 'Invalid nextAction type')
+  if (value.capability !== undefined) check(typeof value.capability === 'string' && /^[a-z][a-z0-9_-]{0,127}$/.test(value.capability), 'Invalid nextAction capability')
+  return { type: value.type, ...(value.capability === undefined ? {} : { capability: value.capability }) }
+}
+
+export function normalizeRuntimeStatus(value) {
+  check(record(value), 'Runtime status must be an object')
+  keys(value, ['state', 'reason', 'retryable', 'nextAction', 'context'], 'runtime status')
+  check(states.has(value.state), 'Invalid runtime state')
+  const result = { state: value.state }
+  if (value.reason !== undefined) {
+    check(typeof value.reason === 'string' && value.reason.length <= 512, 'Invalid runtime reason')
+    result.reason = value.reason
+  }
+  if (value.retryable !== undefined) {
+    check(typeof value.retryable === 'boolean', 'Invalid runtime retryable value')
+    result.retryable = value.retryable
+  }
+  if (value.nextAction !== undefined) result.nextAction = normalizeNextAction(value.nextAction)
+  if (value.context !== undefined) {
+    check(record(value.context), 'Runtime context must be an object')
+    keys(value.context, ['activeDocumentId'], 'runtime context')
+    if (value.context.activeDocumentId !== undefined) check(typeof value.context.activeDocumentId === 'string' && value.context.activeDocumentId.length <= 128, 'Invalid activeDocumentId')
+    result.context = value.context.activeDocumentId === undefined ? {} : { activeDocumentId: value.context.activeDocumentId }
+  }
+  return result
+}
+
+/** Keep recovery metadata across process boundaries without forwarding arbitrary fields. */
+export function serializeAgentError(error) {
+  const result = {
+    code: typeof error?.code === 'string' ? error.code.slice(0, 128) : 'AGENT_HANDLER_ERROR',
+    message: typeof error?.message === 'string' ? error.message.slice(0, 2048) : 'Application handler failed',
+  }
+  // Preserve public platform diagnostics through the renderer/child/MCP
+  // boundaries, without forwarding credentials or arbitrary error fields.
+  if (Number.isInteger(error?.status) && error.status >= 100 && error.status <= 599) result.status = error.status
+  if (typeof error?.requestId === 'string') result.requestId = error.requestId.slice(0, 256)
+  if (typeof error?.authReason === 'string') result.authReason = error.authReason.slice(0, 128)
+  if (typeof error?.reason === 'string') result.reason = error.reason.slice(0, 512)
+  if (typeof error?.retryable === 'boolean') result.retryable = error.retryable
+  if (typeof error?.executionStarted === 'boolean') result.executionStarted = error.executionStarted
+  if (error?.nextAction !== undefined) {
+    try { result.nextAction = normalizeNextAction(error.nextAction) } catch { /* Invalid hints cannot obscure the actual error. */ }
+  }
+  const recovery = {
+    AGENT_OUTCOME_UNKNOWN: { reason: 'execution_outcome_unknown', retryable: false, nextAction: { type: 'inspect_state' } },
+    AGENT_WRITE_BUSY: { reason: 'write_pending_or_unknown', retryable: false, nextAction: { type: 'inspect_state' } },
+    AGENT_IDEMPOTENCY_CONFLICT: { reason: 'idempotency_conflict', retryable: false, nextAction: { type: 'inspect_state' } },
+    AGENT_APP_UNAVAILABLE: { reason: 'app_unavailable', retryable: true, nextAction: { type: 'wait' } },
+    AGENT_APP_NOT_READY: { reason: 'app_not_ready', retryable: true, nextAction: { type: 'wait' } },
+  }[result.code]
+  if (recovery) for (const [key, value] of Object.entries(recovery)) if (result[key] === undefined) result[key] = value
+  // An unknown execution outcome must never acquire an automatic retry hint.
+  if (result.code === 'AGENT_OUTCOME_UNKNOWN') {
+    result.retryable = false
+    result.nextAction = { type: 'inspect_state' }
+  }
+  return result
+}

package/artifact-security.mjs

@@ -0,0 +1,45 @@
+import { basename, extname, join } from 'node:path'
+import { readdir, readFile } from 'node:fs/promises'
+
+// Keep these release rules aligned with appmarket/artifact_security.go. This is
+// a last-line leak check, not a guarantee that arbitrary secrets can be found.
+const credentialRules = [
+  ['embedded-api-key', /(?:^|[^A-Za-z0-9_-])(sk-(?:(?:proj|svcacct|ant-api\d+)-)?[A-Za-z0-9_-]{32,})/g],
+  ['embedded-github-token', /(?:^|[^A-Za-z0-9_])((?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{60,}))/g],
+  ['embedded-slack-token', /(?:^|[^A-Za-z0-9_-])(xox[baprs]-[A-Za-z0-9-]{32,})/g],
+  ['embedded-session-jwt', /(?:^|[^A-Za-z0-9_-])((?:ast_)?eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{32,})/g],
+]
+
+function isPlaceholder(token) {
+  const body = token.replace(/^(?:sk-(?:(?:proj|svcacct|ant-api\d+)-)?|gh[pousr]_|github_pat_|xox[baprs]-)/, '')
+  return /^(?:x+|X+|0+|your[-_].*|replace[-_].*|example[-_].*|placeholder[-_].*)$/.test(body)
+}
+
+export function assertSafeArtifactFile(filePath, data, { allowSourceMaps = false } = {}) {
+  const name = basename(filePath.replaceAll('\\', '/')).toLowerCase()
+  const reject = rule => { throw new Error(`unsafe app artifact [${rule}]: ${filePath}`) }
+  if (name === '.npmrc' || name === '.proxy-app.json' || name === '.env' || name.startsWith('.env.')) {
+    throw new Error(`sensitive file cannot be included in app bundle: ${filePath}`)
+  }
+  if (!allowSourceMaps && name.endsWith('.map')) reject('source-map-file')
+  if (['.key', '.p12', '.pfx', '.jks', '.keystore', '.ppk'].includes(extname(name)) || /^(?:id_rsa|id_dsa|id_ecdsa|id_ed25519)$/.test(name)) reject('private-key-file')
+  const text = typeof data === 'string' ? data : new TextDecoder().decode(data)
+  if (/-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----/.test(text) || /PuTTY-User-Key-File-[23]:/.test(text)) reject('private-key-content')
+  if (!allowSourceMaps && /(?:\/\/[@#]|\/\*[@#])\s*sourceMappingURL\s*=\s*\S/.test(text)) reject('source-map-reference')
+  for (const [rule, pattern] of credentialRules) {
+    pattern.lastIndex = 0
+    for (const match of text.matchAll(pattern)) {
+      if (!isPlaceholder(match[1])) reject(rule)
+    }
+  }
+}
+
+export async function assertSafeArtifactDirectory(directory, prefix = '') {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const filePath = prefix ? `${prefix}/${entry.name}` : entry.name
+    if (entry.isSymbolicLink()) throw new Error(`symbolic links are not allowed in app bundles: ${filePath}`)
+    const absolute = join(directory, entry.name)
+    if (entry.isDirectory()) await assertSafeArtifactDirectory(absolute, filePath)
+    else assertSafeArtifactFile(filePath, await readFile(absolute))
+  }
+}

package/local-dev-credentials.mjs

@@ -0,0 +1,187 @@
+import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { realpathSync } from 'node:fs'
+import { lstat, mkdir, unlink, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const SERVICE = 'cn.proxy-app.local-development'
+const VALUE_PREFIX = 'proxy-app-token-v1:'
+const TIMEOUT_MS = 5000
+const MAX_OUTPUT_BYTES = 128 * 1024
+// security -i reads a bounded line buffer. A longer line can be split into
+// several commands, so it must never be submitted even though it is base64.
+const MAX_INTERACTIVE_COMMAND_BYTES = 4000
+const MEMORY_REASON = '系统安全凭证存储不可用，当前授权仅保存在开发进程内存中。'
+const INVALIDATION_REASON = '无法更新本地授权失效记录，当前授权仅保存在开发进程内存中。'
+
+function normalizeURL(value) {
+  let url
+  try { url = new URL(value) } catch { throw new Error('开发授权缓存需要有效的平台地址。') }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error('开发授权缓存的平台地址不能包含凭证、查询参数或片段。')
+  }
+  return url.origin + url.pathname.replace(/\/+$/, '')
+}
+
+function credentialAccount({ baseURL, portalURL, appID, projectPath, purpose }) {
+  if (!baseURL || !appID?.trim() || !projectPath) throw new Error('开发授权缓存配置不完整。')
+  let project
+  try { project = realpathSync(projectPath) } catch { throw new Error('开发授权缓存需要已存在的项目路径。') }
+  const identity = [
+    normalizeURL(baseURL), normalizeURL(portalURL || baseURL), appID.trim(), project,
+  ]
+  // Keep existing runtime cache identities intact. Developer authorization is
+  // a separate capability and must survive an app user's logout/account switch.
+  if (purpose === 'development') identity.push('development')
+  return createHash('sha256').update(JSON.stringify(identity)).digest('hex')
+}
+
+// No shell is involved. Only a fixed command, a hash and base64 data reach the
+// interactive parser; quotes, newlines and command syntax in a token stay data.
+function encodeToken(token) {
+  return VALUE_PREFIX + Buffer.from(token, 'utf8').toString('base64')
+}
+
+function decodeToken(value) {
+  const stored = value.replace(/\r?\n$/, '')
+  if (!stored.startsWith(VALUE_PREFIX)) return null
+  const encoded = stored.slice(VALUE_PREFIX.length)
+  if (!encoded || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) return null
+  const token = Buffer.from(encoded, 'base64').toString('utf8')
+  return token && encodeToken(token) === stored ? token : null
+}
+
+function runSecurityCommand(file, args, { input = '', timeoutMs }) {
+  return new Promise((resolve) => {
+    let child
+    let timer
+    let finished = false
+    let stdout = ''
+    let bytes = 0
+    const finish = (exitCode) => {
+      if (finished) return
+      finished = true
+      clearTimeout(timer)
+      resolve({ exitCode, stdout: exitCode === 0 ? stdout : '' })
+    }
+    try {
+      child = spawn(file, args, { stdio: ['pipe', 'pipe', 'pipe'], shell: false, windowsHide: true })
+      timer = setTimeout(() => { child.kill('SIGKILL'); finish(null) }, timeoutMs)
+      child.on('error', () => finish(null))
+      child.on('close', (code) => finish(code))
+      child.stdout.on('data', (chunk) => {
+        bytes += chunk.length
+        if (bytes > MAX_OUTPUT_BYTES) { child.kill('SIGKILL'); finish(null) }
+        else stdout += chunk.toString('utf8')
+      })
+      // security may echo input in errors; never forward or retain stderr.
+      child.stderr.resume()
+      child.stdin.on('error', () => finish(null))
+      child.stdin.end(input)
+    } catch { finish(null) }
+  })
+}
+
+/**
+ * Cache a Portal login for one platform, app and real project directory.
+ * App versions and local server ports intentionally do not affect its identity.
+ * runCommand is injectable and returns { exitCode, stdout }; it receives
+ * (executable, args, { input, timeoutMs }). Tokens never appear in args.
+ * stateDirectory contains only non-secret invalidation markers, never tokens.
+ */
+export function createLocalCredentialStore({
+  baseURL, portalURL = '', appID, projectPath,
+  purpose = 'runtime',
+  platform = process.platform,
+  runCommand = runSecurityCommand,
+  timeoutMs = TIMEOUT_MS,
+  stateDirectory = join(homedir(), 'Library', 'Caches', 'proxy-app', 'credentials'),
+}) {
+  if (!['runtime', 'development'].includes(purpose)) throw new Error('未知的授权缓存用途。')
+  const account = credentialAccount({ baseURL, portalURL, appID, projectPath, purpose })
+  const markerPath = join(stateDirectory, account + '.disabled')
+  const boundedTimeout = Number.isFinite(timeoutMs) ? Math.max(1, Math.min(timeoutMs, TIMEOUT_MS)) : TIMEOUT_MS
+  let kind = platform === 'darwin' ? 'keychain' : 'memory'
+  let reason = kind === 'keychain' ? '' : MEMORY_REASON
+  let memoryToken = null
+  let queue = Promise.resolve()
+
+  const fallback = (message = MEMORY_REASON) => { kind = 'memory'; reason = message }
+  const serial = (operation) => {
+    const pending = queue.then(operation)
+    queue = pending.catch(() => undefined)
+    return pending
+  }
+  const security = async (args, input = '') => {
+    let timer
+    try {
+      const result = await Promise.race([
+        Promise.resolve().then(() => runCommand('/usr/bin/security', args, { input, timeoutMs: boundedTimeout })),
+        new Promise((resolve) => { timer = setTimeout(() => resolve(null), boundedTimeout) }),
+      ])
+      if (!result || typeof result.stdout !== 'string' || Buffer.byteLength(result.stdout) > MAX_OUTPUT_BYTES) return null
+      return { exitCode: result.exitCode, stdout: result.stdout }
+    } catch { return null } finally { clearTimeout(timer) }
+  }
+  const invalidated = async () => {
+    try { await lstat(markerPath); return true } catch (error) {
+      if (error?.code === 'ENOENT') return false
+      fallback(INVALIDATION_REASON)
+      return true
+    }
+  }
+  const invalidate = async () => {
+    try {
+      await mkdir(stateDirectory, { recursive: true, mode: 0o700 })
+      await writeFile(markerPath, 'Automatic restore is disabled until a new authorization is saved.\n', { flag: 'wx', mode: 0o600 })
+      return true
+    } catch (error) {
+      if (error?.code === 'EEXIST') return true
+      fallback(INVALIDATION_REASON)
+      return false
+    }
+  }
+
+  return {
+    get kind() { return kind },
+    get reason() { return reason },
+    load: () => serial(async () => {
+      if (memoryToken || kind !== 'keychain' || await invalidated()) return memoryToken
+      const result = await security(['find-generic-password', '-s', SERVICE, '-a', account, '-w'])
+      if (result?.exitCode === 44) return null // errSecItemNotFound
+      if (result?.exitCode !== 0) { fallback(); return null }
+      const token = decodeToken(result.stdout)
+      if (!token) { fallback(); return null }
+      memoryToken = token
+      return token
+    }),
+    save: (token) => serial(async () => {
+      if (typeof token !== 'string' || !token || Buffer.byteLength(token) > 64 * 1024) {
+        throw new Error('开发授权凭证为空或格式无效。')
+      }
+      memoryToken = token
+      if (platform !== 'darwin' || !await invalidate() || kind !== 'keychain') return
+      const encoded = encodeToken(token)
+      const command = 'add-generic-password -U -s ' + SERVICE + ' -a ' + account + ' -w ' + encoded + '\n'
+      if (Buffer.byteLength(command) > MAX_INTERACTIVE_COMMAND_BYTES) { fallback(); return }
+      const result = await security(['-i'], command)
+      if (result?.exitCode !== 0) { fallback(); return }
+      // An interactive command's process status alone does not prove the item
+      // was updated. Keep restore disabled until the saved token is verified.
+      const saved = await security(['find-generic-password', '-s', SERVICE, '-a', account, '-w'])
+      if (saved?.exitCode !== 0 || saved.stdout.replace(/\r?\n$/, '') !== encoded) { fallback(); return }
+      try { await unlink(markerPath) } catch (error) {
+        if (error?.code !== 'ENOENT') fallback(INVALIDATION_REASON)
+      }
+    }),
+    clear: () => serial(async () => {
+      memoryToken = null
+      if (platform !== 'darwin' || !await invalidate()) return
+      const result = await security(['delete-generic-password', '-s', SERVICE, '-a', account])
+      if (result?.exitCode !== 0 && result?.exitCode !== 44) fallback()
+      // Keep the marker even if deletion succeeds. Only a successfully saved
+      // new login may enable automatic restore after an explicit logout.
+    }),
+  }
+}