@drawcall/market 0.1.75 → 0.1.77

package/src/cli.ts

@@ -8,7 +8,7 @@ import * as oauthClient from 'openid-client'
 import { ASSET_TYPES, type AssetAccess, type AssetType } from './schemas.js'
 import { installCommand } from './commands/install.js'
 import { searchCommand } from './commands/search.js'
-import { agentCommand, waitAgentCommand } from './commands/agent.js'
+import { agentCommand } from './commands/agent.js'
 import { generateCommand } from './commands/generate.js'
 import { generateInstallCommand } from './commands/generate-install.js'
 import { listCommand } from './commands/list.js'
@@ -33,6 +33,12 @@ const DEVICE_CLIENT_ID = 'market-cli'
 const collect = (value: string, previous: string[]): string[] => previous.concat(value)
 
 const typeOption = new Option('--type <type>', 'Asset type').choices([...ASSET_TYPES])
+const referenceImageOption = new Option(
+  '--reference-image <file-or-url>',
+  'Reference image the result should match: file path or http(s) URL (repeatable)',
+)
+  .argParser(collect)
+  .default([])
 // Omitted → the server picks the default from your entitlement (private if you hold market:private,
 // else public). `--access private` requires that entitlement.
 const accessOption = new Option('--access <access>', 'Asset visibility').choices([
@@ -193,49 +199,21 @@ const agent = program
   .description('Plan, find, judge and generate a set of assets from a goal')
   .argument('[goal]', 'What you need, in plain language')
   .addOption(apiOption)
-  .option('--image <path>', 'Reference image, repeatable', collect, [])
+  .addOption(referenceImageOption)
   .option('--json', 'Output JSON', false)
-  .option('--defer-generation', 'Wait for explicit approval before provider generation', false)
-  .option('--approval-file <path>', 'Start/recovery control containing "approve" or "cancel"')
-  .option('--run-file <path>', 'Durable sidecar for the deferred run ID')
-  .option('--wait-run-file <path>', 'Recover and wait for an existing deferred run')
   .action(
     async (
       goal: string | undefined,
-      opts: {
-        api?: string
-        image: string[]
-        json: boolean
-        deferGeneration: boolean
-        approvalFile?: string
-        runFile?: string
-        waitRunFile?: string
-      },
+      opts: { api?: string; referenceImage: string[]; json: boolean },
     ) => {
-      if (opts.waitRunFile) {
-        if (goal || opts.deferGeneration || opts.runFile || opts.image.length) {
-          throw new Error(
-            '--wait-run-file cannot be combined with a goal or deferred-start options',
-          )
-        }
-        await waitAgentCommand(opts.waitRunFile, {
-          baseUrl: opts.api,
-          json: opts.json,
-          approvalFile: opts.approvalFile,
-        })
-        return
-      }
       if (!goal) {
         agent.help({ error: true })
         return
       }
       await agentCommand(goal, {
         baseUrl: opts.api,
-        images: opts.image,
+        referenceImages: opts.referenceImage,
         json: opts.json,
-        deferGeneration: opts.deferGeneration,
-        approvalFile: opts.approvalFile,
-        runFile: opts.runFile,
       })
     },
   )
@@ -305,12 +283,19 @@ const generate = program
   .argument('[description]', 'Asset prompt (omit when using a subcommand)')
   .addOption(typeOption)
   .addOption(apiOption)
+  .addOption(referenceImageOption)
   .option('--cwd <dir>', 'Project directory')
   .addOption(accessOption)
   .action(
     async (
       description: string | undefined,
-      opts: { type?: AssetType; api?: string; cwd?: string; access?: AssetAccess },
+      opts: {
+        type?: AssetType
+        api?: string
+        referenceImage: string[]
+        cwd?: string
+        access?: AssetAccess
+      },
     ) => {
       if (!description) {
         generate.help({ error: true })
@@ -320,6 +305,7 @@ const generate = program
       await generateCommand(description, {
         type: opts.type,
         baseUrl: opts.api,
+        referenceImages: opts.referenceImage,
         cwd: opts.cwd,
         access: opts.access,
       })

package/src/commands/agent.ts

@@ -1,46 +1,20 @@
-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, AgentError, type AgentInput } from '../agent.js'
+import { agentAndWait } from '../agent.js'
+import { loadReferenceImages } from './reference-images.js'
 import { assetVersionRef } from '../output.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
-}
+import type { AgentResult } from '../schemas.js'
 
 export interface AgentCommandOptions {
-  images?: string[]
+  /** `--reference-image` values: file paths or http(s) URLs. */
+  referenceImages?: 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))
+  const referenceImages = await loadReferenceImages(opts.referenceImages ?? [])
 
   const spinner = ora({
     text: `Working on "${goal}"`,
@@ -48,435 +22,11 @@ export async function agentCommand(goal: string, opts: AgentCommandOptions): Pro
     isSilent: !process.stderr.isTTY,
   }).start()
 
-  try {
-    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) {
-    spinner.stop()
-    throw err
-  }
-}
-
-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
+  const result = await agentAndWait(client, {
+    goal,
+    referenceImages: referenceImages.length ? referenceImages : undefined,
+  }).finally(() => spinner.stop())
+  printResult(result, opts.json ?? false)
 }
 
 function printResult(result: AgentResult, asJson: boolean): void {
@@ -499,16 +49,3 @@ function printResult(result: AgentResult, asJson: boolean): void {
     console.log(`Notes: ${notes}`)
   }
 }
-
-async function toDataUrl(path: string): Promise<string> {
-  const data = await readFile(path)
-  return `data:${mimeFor(path)};base64,${data.toString('base64')}`
-}
-
-function mimeFor(path: string): string {
-  const ext = extname(path).toLowerCase()
-  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg'
-  if (ext === '.webp') return 'image/webp'
-  if (ext === '.gif') return 'image/gif'
-  return 'image/png'
-}

package/src/commands/generate.ts

@@ -5,10 +5,13 @@ import type { MarketClient } from '../client.js'
 import { resolve } from '../resolve.js'
 import { install as runInstall } from '../install.js'
 import { generatedInstallResult, generationStartedResult } from '../output.js'
+import { loadReferenceImages } from './reference-images.js'
 import type { AssetAccess, AssetType } from '../schemas.js'
 
 export interface GenerateCommandOptions {
   type: AssetType
+  /** `--reference-image` values: file paths or http(s) URLs. */
+  referenceImages?: string[]
   cwd?: string
   baseUrl?: string
   access?: AssetAccess
@@ -18,6 +21,7 @@ export async function generateCommand(
   description: string,
   opts: GenerateCommandOptions,
 ): Promise<void> {
+  const referenceImages = await loadReferenceImages(opts.referenceImages ?? [])
   const { client, baseUrl, authToken } = await getCliClient({
     baseUrl: opts.baseUrl,
     requireAuth: true,
@@ -27,6 +31,7 @@ export async function generateCommand(
     const started = await startGeneration(client, {
       description,
       type: opts.type,
+      referenceImages: referenceImages.length ? referenceImages : undefined,
       access: opts.access,
     })
     // Fast providers finish inline; slow, job-based ones return a job to poll.

package/src/commands/reference-images.ts

@@ -0,0 +1,25 @@
+import { readFile } from 'node:fs/promises'
+import { extname } from 'node:path'
+
+/**
+ * Resolve repeatable `--reference-image` values into what the Market API takes: an http(s) URL
+ * passes through untouched (the provider fetches it), a local file becomes a data URI.
+ */
+export function loadReferenceImages(refs: string[]): Promise<string[]> {
+  return Promise.all(refs.map(loadReferenceImage))
+}
+
+async function loadReferenceImage(ref: string): Promise<string> {
+  if (ref.startsWith('http://') || ref.startsWith('https://')) return ref
+  const data = await readFile(ref)
+  return `data:${mimeFor(ref)};base64,${data.toString('base64')}`
+}
+
+function mimeFor(path: string): string {
+  const ext = extname(path).toLowerCase()
+  if (ext === '.png') return 'image/png'
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg'
+  if (ext === '.webp') return 'image/webp'
+  if (ext === '.gif') return 'image/gif'
+  throw new Error(`Unsupported reference image type "${ext}": ${path}`)
+}