@drawcall/market 0.1.59 → 0.1.61

package/src/commands/agent.ts

@@ -1,18 +1,44 @@
-import { readFile } from 'node:fs/promises'
-import { extname } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { link, mkdir, open, readFile, rm } from 'node:fs/promises'
+import { basename, dirname, extname, join } from 'node:path'
+import { ORPCError } from '@orpc/client'
 import ora from 'ora'
 import { getCliClient } from '../cli-client.js'
-import { agentAndWait } from '../agent.js'
+import { agentAndWait, AgentError, type AgentInput } from '../agent.js'
 import { assetVersionRef } from '../output.js'
-import type { AgentResult } from '../schemas.js'
+import type { AgentControlResult, AgentResult, AgentRunStatus } from '../schemas.js'
+
+export type AgentControlClient = {
+  asset: {
+    agent: {
+      startDeferred(input: DeferredAgentInput & { runId: string }): Promise<{ runId: string }>
+      status(input: { runId: string }): Promise<AgentRunStatus>
+      approve(input: { runId: string }): Promise<AgentControlResult>
+      cancel(input: { runId: string }): Promise<AgentControlResult>
+    }
+  }
+}
+
+type DeferredAgentInput = Pick<AgentInput, 'goal'>
+type AgentDiagnostic = (line: string) => void
+
+interface DeferredRunHandle {
+  version: 1
+  runId: string
+  input: DeferredAgentInput
+}
 
 export interface AgentCommandOptions {
   images?: string[]
   json?: boolean
   baseUrl?: string
+  deferGeneration?: boolean
+  approvalFile?: string
+  runFile?: string
 }
 
 export async function agentCommand(goal: string, opts: AgentCommandOptions): Promise<void> {
+  validateDeferredOptions(opts)
   const { client } = await getCliClient({ baseUrl: opts.baseUrl, requireAuth: true })
   const images = await Promise.all((opts.images ?? []).map(toDataUrl))
 
@@ -23,7 +49,9 @@ export async function agentCommand(goal: string, opts: AgentCommandOptions): Pro
   }).start()
 
   try {
-    const result = await agentAndWait(client, { goal, images: images.length ? images : undefined })
+    const result = opts.deferGeneration
+      ? await runDeferredAgent(client, { goal }, requiredApprovalFile(opts), requiredRunFile(opts))
+      : await agentAndWait(client, { goal, images: images.length ? images : undefined })
     spinner.stop()
     printResult(result, opts.json ?? false)
   } catch (err) {
@@ -32,6 +60,425 @@ export async function agentCommand(goal: string, opts: AgentCommandOptions): Pro
   }
 }
 
+export interface AgentWaitCommandOptions {
+  json?: boolean
+  baseUrl?: string
+  approvalFile?: string
+}
+
+export async function waitAgentCommand(
+  runFile: string,
+  opts: AgentWaitCommandOptions,
+): Promise<void> {
+  const { client } = await getCliClient({ baseUrl: opts.baseUrl, requireAuth: true })
+  const handle = await readRunHandle(runFile)
+  await ensureDeferredStarted(client, handle)
+  const { runId } = handle
+  const interrupt = interruptSignal()
+  const spinner = ora({
+    text: `Waiting for Market agent run ${runId}`,
+    isEnabled: Boolean(process.stderr.isTTY),
+    isSilent: !process.stderr.isTTY,
+  }).start()
+
+  let settled = false
+  try {
+    const result = opts.approvalFile
+      ? await resumeExistingAgent(
+          client,
+          runId,
+          opts.approvalFile,
+          interrupt.signal,
+          writeAgentDiagnostic,
+        )
+      : await waitForExistingAgent(client, runId, interrupt.signal, writeAgentDiagnostic)
+    settled = true
+    spinner.stop()
+    printResult(result, opts.json ?? false)
+  } catch (error) {
+    spinner.stop()
+    throw error
+  } finally {
+    interrupt.dispose()
+    if (!settled && opts.approvalFile) {
+      await client.asset.agent.cancel({ runId }).catch(() => undefined)
+    }
+  }
+}
+
+function validateDeferredOptions(opts: AgentCommandOptions): void {
+  if (opts.deferGeneration && !opts.approvalFile) {
+    throw new Error('--defer-generation requires --approval-file <path>')
+  }
+  if (opts.deferGeneration && !opts.runFile) {
+    throw new Error('--defer-generation requires --run-file <path>')
+  }
+  if (opts.approvalFile && !opts.deferGeneration) {
+    throw new Error('--approval-file requires --defer-generation')
+  }
+  if (opts.runFile && !opts.deferGeneration) {
+    throw new Error('--run-file requires --defer-generation')
+  }
+  if (opts.deferGeneration && opts.images?.length) {
+    throw new Error('--image is not supported with --defer-generation')
+  }
+}
+
+function requiredRunFile(opts: AgentCommandOptions): string {
+  if (!opts.runFile) throw new Error('Run file is required')
+  return opts.runFile
+}
+
+function requiredApprovalFile(opts: AgentCommandOptions): string {
+  if (!opts.approvalFile) throw new Error('Approval file is required')
+  return opts.approvalFile
+}
+
+export async function runDeferredAgent(
+  client: AgentControlClient,
+  input: DeferredAgentInput,
+  approvalFile: string,
+  runFile: string,
+  emitDiagnostic: AgentDiagnostic = writeAgentDiagnostic,
+): Promise<AgentResult> {
+  const interrupt = interruptSignal()
+  const watch = new AbortController()
+  const stopWatch = () => watch.abort(interrupt.signal.reason)
+  interrupt.signal.addEventListener('abort', stopWatch, { once: true })
+
+  const runId = randomUUID()
+  const handle = { version: 1, runId, input } satisfies DeferredRunHandle
+  let runReachable = false
+  let settled = false
+  try {
+    // Persist the client-selected idempotency key and restart input before the
+    // RPC. A lost start response is recoverable without creating a second run.
+    await persistRunHandle(runFile, handle)
+    emitDiagnostic(runHandleDiagnosticLine(runId, runFile))
+    await ensureDeferredStarted(client, handle)
+    runReachable = true
+    const outcome = await resumeExistingAgent(
+      client,
+      runId,
+      approvalFile,
+      watch.signal,
+      emitDiagnostic,
+    )
+    settled = true
+    return outcome
+  } finally {
+    watch.abort()
+    interrupt.dispose()
+    if (!settled && runReachable) {
+      try {
+        await client.asset.agent.cancel({ runId })
+      } catch {
+        // Best-effort cleanup must not replace the actionable local error that
+        // brought us here. Before approval, the server run remains safely gated
+        // even if this request is lost.
+      }
+    }
+  }
+}
+
+export function runHandleDiagnosticLine(runId: string, runFile: string): string {
+  return JSON.stringify({ event: 'market.agent.run.persisted', runId, runFile })
+}
+
+function writeAgentDiagnostic(line: string): void {
+  process.stderr.write(`${line}\n`)
+}
+
+export function waitForExistingAgent(
+  client: AgentControlClient,
+  runId: string,
+  signal: AbortSignal = new AbortController().signal,
+  emitDiagnostic: AgentDiagnostic = ignoreDiagnostic,
+): Promise<AgentResult> {
+  return waitForResult(client, runId, signal, emitDiagnostic)
+}
+
+export async function resumeExistingAgent(
+  client: AgentControlClient,
+  runId: string,
+  approvalFile: string,
+  signal: AbortSignal = new AbortController().signal,
+  emitDiagnostic: AgentDiagnostic = ignoreDiagnostic,
+): Promise<AgentResult> {
+  const operation = new AbortController()
+  const abortOperation = () => operation.abort(signal.reason)
+  if (signal.aborted) abortOperation()
+  else signal.addEventListener('abort', abortOperation, { once: true })
+  try {
+    const result = waitForResult(client, runId, operation.signal, emitDiagnostic).then(
+      (value) => ({ kind: 'result' as const, value }),
+      (error: unknown) => ({ kind: 'error' as const, error }),
+    )
+    const decision = waitForApprovalFile(approvalFile, operation.signal).then(
+      (value) => ({ kind: 'decision' as const, value }),
+      (error: unknown) => ({ kind: 'error' as const, error }),
+    )
+    const first = await Promise.race([result, decision])
+    if (first.kind === 'error') throw first.error
+    if (first.kind === 'result') return first.value
+
+    if (operation.signal.aborted) throw abortReason(operation.signal)
+    const controlRequest =
+      first.value === 'approve'
+        ? client.asset.agent.approve({ runId })
+        : client.asset.agent.cancel({ runId })
+    const control = await raceAbort(controlRequest, operation.signal)
+    if (!control.accepted && control.state !== 'generation-started') {
+      if (isSettledControlState(control.state)) return unwrapResult(await result)
+      throw new AgentError(`Agent ${first.value} rejected: ${control.state}`)
+    }
+    if (first.value === 'cancel' && control.accepted) {
+      // Observe the durable terminal status before returning the cancellation
+      // error so callers receive generationStarted evidence for handle cleanup.
+      return unwrapResult(await result)
+    }
+    return unwrapResult(await result)
+  } finally {
+    operation.abort()
+    signal.removeEventListener('abort', abortOperation)
+  }
+}
+
+function unwrapResult(
+  outcome: { kind: 'result'; value: AgentResult } | { kind: 'error'; error: unknown },
+): AgentResult {
+  if (outcome.kind === 'error') throw outcome.error
+  return outcome.value
+}
+
+function isSettledControlState(state: AgentControlResult['state']): boolean {
+  return state === 'completed' || state === 'failed' || state === 'cancelled'
+}
+
+async function waitForResult(
+  client: AgentControlClient,
+  runId: string,
+  signal: AbortSignal,
+  emitDiagnostic: AgentDiagnostic,
+): Promise<AgentResult> {
+  for (;;) {
+    if (signal.aborted) throw abortReason(signal)
+    const status = await raceAbort(client.asset.agent.status({ runId }), signal)
+    const result = settledResult(runId, status, emitDiagnostic)
+    if (result) return result
+    if (
+      status.status === 'running' &&
+      (status.generation === 'deferred' || status.generation === 'awaiting-approval')
+    ) {
+      await abortableDelay(250, signal)
+    }
+  }
+}
+
+function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(abortReason(signal))
+  return new Promise<T>((resolve, reject) => {
+    signal.addEventListener('abort', aborted, { once: true })
+    promise.then(completed, failed)
+
+    function completed(value: T): void {
+      signal.removeEventListener('abort', aborted)
+      resolve(value)
+    }
+    function failed(error: unknown): void {
+      signal.removeEventListener('abort', aborted)
+      reject(error)
+    }
+    function aborted(): void {
+      reject(abortReason(signal))
+    }
+  })
+}
+
+function settledResult(
+  runId: string,
+  status: AgentRunStatus,
+  emitDiagnostic: AgentDiagnostic,
+): AgentResult | undefined {
+  if (status.status === 'running') return undefined
+  emitDiagnostic(agentTerminalDiagnosticLine(runId, status))
+  if (status.status === 'completed') return status.result
+  if (status.status === 'failed') throw new AgentError(status.error)
+  throw new AgentError('Agent run cancelled')
+}
+
+export function agentTerminalDiagnosticLine(
+  runId: string,
+  status: Exclude<AgentRunStatus, { status: 'running' }>,
+): string {
+  return JSON.stringify({
+    event: 'market.agent.run.terminal',
+    runId,
+    status: status.status,
+    generationStarted: status.generationStarted ?? null,
+  })
+}
+
+function ignoreDiagnostic(): void {}
+
+async function waitForApprovalFile(
+  path: string,
+  signal: AbortSignal,
+): Promise<'approve' | 'cancel'> {
+  for (;;) {
+    if (signal.aborted) throw abortReason(signal)
+    try {
+      const value = (await readFile(path, 'utf8')).trim()
+      if (value === 'approve' || value === 'cancel') return value
+      if (value) {
+        throw new Error(`Approval file must contain exactly "approve" or "cancel": ${path}`)
+      }
+    } catch (error) {
+      if (!isMissingFile(error)) throw error
+    }
+    await abortableDelay(100, signal)
+  }
+}
+
+function interruptSignal(): { signal: AbortSignal; dispose(): void } {
+  const controller = new AbortController()
+  const onSigint = () => controller.abort(new AgentError('Interrupted by SIGINT'))
+  const onSigterm = () => controller.abort(new AgentError('Interrupted by SIGTERM'))
+  process.once('SIGINT', onSigint)
+  process.once('SIGTERM', onSigterm)
+  return {
+    signal: controller.signal,
+    dispose() {
+      process.off('SIGINT', onSigint)
+      process.off('SIGTERM', onSigterm)
+    },
+  }
+}
+
+function abortableDelay(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.reject(abortReason(signal))
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(done, ms)
+    signal.addEventListener('abort', aborted, { once: true })
+
+    function done(): void {
+      signal.removeEventListener('abort', aborted)
+      resolve()
+    }
+    function aborted(): void {
+      clearTimeout(timeout)
+      reject(abortReason(signal))
+    }
+  })
+}
+
+function abortReason(signal: AbortSignal): Error {
+  return signal.reason instanceof Error ? signal.reason : new AgentError('Agent command aborted')
+}
+
+function isMissingFile(error: unknown): boolean {
+  return hasErrorCode(error, 'ENOENT')
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return error instanceof Error && 'code' in error && error.code === code
+}
+
+async function persistRunHandle(path: string, handle: DeferredRunHandle): Promise<void> {
+  const directory = dirname(path)
+  await mkdir(directory, { recursive: true })
+  const temporary = join(directory, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`)
+  let file: Awaited<ReturnType<typeof open>> | undefined
+  try {
+    file = await open(temporary, 'wx', 0o600)
+    await file.writeFile(`${JSON.stringify(handle)}\n`, 'utf8')
+    await file.sync()
+    await file.close()
+    file = undefined
+
+    // A same-directory hard link is an atomic create-if-absent. Refusing to
+    // replace a previous handle prevents a new run from orphaning an older one.
+    try {
+      await link(temporary, path)
+    } catch (error) {
+      if (hasErrorCode(error, 'EEXIST')) {
+        throw new Error(`Run file already exists; recover or remove it first: ${path}`, {
+          cause: error,
+        })
+      }
+      throw error
+    }
+    await rm(temporary)
+    const directoryHandle = await open(directory, 'r')
+    try {
+      await directoryHandle.sync()
+    } finally {
+      await directoryHandle.close()
+    }
+  } finally {
+    await file?.close().catch(() => undefined)
+    await rm(temporary, { force: true }).catch(() => undefined)
+  }
+}
+
+async function readRunHandle(path: string): Promise<DeferredRunHandle> {
+  let value: unknown
+  try {
+    value = JSON.parse(await readFile(path, 'utf8'))
+  } catch (error) {
+    throw new Error(`Run file does not contain a valid Market run handle: ${path}`, {
+      cause: error,
+    })
+  }
+  if (!isDeferredRunHandle(value)) {
+    throw new Error(`Run file does not contain a valid Market run handle: ${path}`)
+  }
+  return value
+}
+
+function isDeferredRunHandle(value: unknown): value is DeferredRunHandle {
+  if (!value || typeof value !== 'object') return false
+  const record = value as Record<string, unknown>
+  const input = record.input
+  return (
+    record.version === 1 &&
+    typeof record.runId === 'string' &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(record.runId) &&
+    Boolean(input) &&
+    typeof input === 'object' &&
+    typeof (input as Record<string, unknown>).goal === 'string' &&
+    Object.keys(input as Record<string, unknown>).length === 1
+  )
+}
+
+async function ensureDeferredStarted(
+  client: AgentControlClient,
+  handle: DeferredRunHandle,
+): Promise<void> {
+  try {
+    const started = await client.asset.agent.startDeferred({
+      ...handle.input,
+      runId: handle.runId,
+    })
+    if (started.runId !== handle.runId) {
+      throw new Error('Market returned a different deferred run ID')
+    }
+  } catch (startError) {
+    if (isAuthoritativeStartRejection(startError)) throw startError
+    // The start response may be lost after the Durable Object committed. A
+    // successful owner-checked status proves that this exact run is reachable.
+    try {
+      await client.asset.agent.status({ runId: handle.runId })
+    } catch {
+      throw startError
+    }
+  }
+}
+
+function isAuthoritativeStartRejection(error: unknown): boolean {
+  return error instanceof ORPCError && error.status >= 400 && error.status < 500
+}
+
 function printResult(result: AgentResult, asJson: boolean): void {
   if (asJson) {
     console.log(JSON.stringify(result))

package/src/contract.ts

@@ -3,6 +3,8 @@ import { z } from 'zod'
 import type { AssetFileManifest } from './schemas.js'
 import {
   MAX_UPLOAD_ZIP_SIZE_BYTES,
+  agentControlResultSchema,
+  agentDeferredStartSchema,
   agentRunStatusSchema,
   agentStartSchema,
   agentStatusSchema,
@@ -143,10 +145,16 @@ export const contract = {
     // The agent plans, searches, judges and (where supported) generates a set of
     // assets from a goal. `start` kicks off an async run; `status` long-polls it
     // (blocks until the run settles or a heartbeat window elapses). The
-    // `agentAndWait` client helper drives both.
+    // `agentAndWait` drives ordinary runs. A safety-critical deferred caller
+    // uses fail-closed `startDeferred`, observes `status`, then calls `approve`
+    // or `cancel`. Deferred semantics deliberately do not exist on `start`:
+    // an older worker could strip an unknown optional flag and spend immediately.
     agent: {
       start: oc.input(agentStartSchema).output(z.object({ runId: z.string() })),
+      startDeferred: oc.input(agentDeferredStartSchema).output(z.object({ runId: z.string() })),
       status: oc.input(agentStatusSchema).output(agentRunStatusSchema),
+      approve: oc.input(agentStatusSchema).output(agentControlResultSchema),
+      cancel: oc.input(agentStatusSchema).output(agentControlResultSchema),
     },
   },
 

package/src/index.ts

@@ -67,7 +67,11 @@ export {
   updateProfileSchema,
   listAssetsSchema,
   agentStartSchema,
+  agentDeferredStartSchema,
   agentStatusSchema,
+  agentGenerationStateSchema,
+  agentControlStateSchema,
+  agentControlResultSchema,
   agentResultAssetSchema,
   agentResultSchema,
   agentRunStatusSchema,
@@ -83,6 +87,9 @@ export type {
   AgentResultAsset,
   AgentResult,
   AgentRunStatus,
+  AgentGenerationState,
+  AgentControlState,
+  AgentControlResult,
   GenerateResponse,
   GenerateJobStatus,
 } from './schemas.js'

package/src/schemas.ts

@@ -144,21 +144,53 @@ export type GenerateJobStatus = z.infer<typeof generateJobStatusSchema>
 // The agent takes a natural-language goal (which carries the count and kinds,
 // e.g. "3 low poly stones" or "a template for a zombie game, none if no fit")
 // and optional reference images as base64 (raw or data URLs).
-export const agentStartSchema = z.object({
+export const agentStartSchema = z.strictObject({
   goal: z.string().min(3).max(1000),
   images: z.array(z.string()).optional(),
 })
 
+// A distinct procedure lets safety-critical callers fail closed against an
+// older worker: an unknown `startDeferred` starts nothing. Deferred runs are
+// goal-only because their restart input is persisted until the wall deadline;
+// accepting unbounded base64 reference images would make that unsafe.
+export const agentDeferredStartSchema = z.strictObject({
+  goal: agentStartSchema.shape.goal,
+  runId: z.string().uuid(),
+})
+
 export const agentStatusSchema = z.object({
   runId: z.string().min(1),
 })
 
+export const agentGenerationStateSchema = z.enum([
+  'deferred',
+  'awaiting-approval',
+  'approved',
+  'generation-started',
+])
+export type AgentGenerationState = z.infer<typeof agentGenerationStateSchema>
+
+export const agentControlStateSchema = z.enum([
+  ...agentGenerationStateSchema.options,
+  'completed',
+  'failed',
+  'cancelled',
+])
+export type AgentControlState = z.infer<typeof agentControlStateSchema>
+
+export const agentControlResultSchema = z.object({
+  accepted: z.boolean(),
+  state: agentControlStateSchema,
+})
+export type AgentControlResult = z.infer<typeof agentControlResultSchema>
+
 // One chosen asset: a verified, installable `name@version` (the agent only
 // returns names the catalog resolved) plus a note on what it contributes.
 export const agentResultAssetSchema = z.object({
   name: assetNameSchema,
   version: semverSchema,
   notes: z.string(),
+  origin: z.enum(['catalog', 'generated']),
 })
 export type AgentResultAsset = z.infer<typeof agentResultAssetSchema>
 
@@ -171,12 +203,27 @@ export const agentResultSchema = z.object({
 })
 export type AgentResult = z.infer<typeof agentResultSchema>
 
-// An agent run is an async job: it is running, or it finished with a result, or
-// it failed. A discriminated union keeps "completed without a result" and
-// "failed without an error" unrepresentable.
+// An agent run is an async job: it is running (with optional generation-gate
+// progress), completed, failed, or explicitly cancelled. A discriminated union
+// keeps "completed without a result" and "failed without an error"
+// unrepresentable.
 export const agentRunStatusSchema = z.discriminatedUnion('status', [
-  z.object({ status: z.literal('running') }),
-  z.object({ status: z.literal('completed'), result: agentResultSchema }),
-  z.object({ status: z.literal('failed'), error: z.string() }),
+  z.object({
+    status: z.literal('running'),
+    // Optional so a new client can still read a running response from an older
+    // worker during a rolling deploy.
+    generation: agentGenerationStateSchema.optional(),
+  }),
+  z.object({
+    status: z.literal('completed'),
+    result: agentResultSchema,
+    generationStarted: z.boolean().optional(),
+  }),
+  z.object({
+    status: z.literal('failed'),
+    error: z.string(),
+    generationStarted: z.boolean().optional(),
+  }),
+  z.object({ status: z.literal('cancelled'), generationStarted: z.boolean().optional() }),
 ])
 export type AgentRunStatus = z.infer<typeof agentRunStatusSchema>