feat: add canonical typed tool outputs

packages/tasks/tool-tasks/src/index.ts

@@ -30,12 +30,55 @@ export const Config: z<Config> = z.object({
   maxWaitTimeoutMs: z.number().min(1).default(600_000),
 })
 
+/** Task state safe for model-authored programs; ownership/bookkeeping fields are omitted. */
+export interface PublicTaskSnapshot {
+  id: string
+  kind: string
+  label: string
+  status: TaskSnapshot['status']
+  detail?: string
+  startedAt: number
+  finishedAt?: number
+}
+
+/** Shared schema for task-control outputs. */
+const PUBLIC_TASK_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    id: { type: 'string', required: true },
+    kind: { type: 'string', required: true },
+    label: { type: 'string', required: true },
+    status: {
+      type: 'string',
+      required: true,
+      enum: ['running', 'stopping', 'completed', 'killed', 'failed'],
+    },
+    detail: { type: 'string' },
+    startedAt: { type: 'integer', required: true },
+    finishedAt: { type: 'integer' },
+  },
+} as const
+
+/** Remove task ownership and notification bookkeeping from a registry snapshot. */
+function publicTask(snapshot: TaskSnapshot): PublicTaskSnapshot {
+  return {
+    id: snapshot.id,
+    kind: snapshot.kind,
+    label: snapshot.label,
+    status: snapshot.status,
+    ...snapshot.detail !== undefined ? { detail: snapshot.detail } : {},
+    startedAt: snapshot.startedAt,
+    ...snapshot.finishedAt !== undefined ? { finishedAt: snapshot.finishedAt } : {},
+  }
+}
+
 /**
  * Render generic status with optional producer detail.
  * @param snapshot - task state to render.
  * @returns a bracketed status line.
  */
-export function statusLine(snapshot: TaskSnapshot): string {
+export function statusLine(snapshot: Pick<TaskSnapshot, 'status' | 'detail'>): string {
   return snapshot.detail !== undefined
     ? `[status: ${snapshot.status}, ${snapshot.detail}]`
     : `[status: ${snapshot.status}]`
@@ -98,6 +141,21 @@ export function apply(ctx: Context, config: Config): void {
       wait: { type: 'boolean', description: 'Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive.' },
       timeout_ms: { type: 'number', description: 'Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum.' },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          text: { type: 'string', required: true },
+          task: { ...PUBLIC_TASK_SCHEMA, required: true },
+        },
+      },
+      render: (_args, value) => {
+        const body = value.text.length > 0 ? value.text : '(no new output)'
+        const separator = body.endsWith('\n') ? '' : '\n'
+        return [{ type: 'text', text: `${body}${separator}${statusLine(value.task)}` }]
+      },
+    },
     async execute(args, exec) {
       const id = validateTaskId(args.task_id)
       if (args.wait === true) {
@@ -105,9 +163,7 @@ export function apply(ctx: Context, config: Config): void {
         await ctx.tasks.wait(id, timeout, exec.agent, exec.signal)
       }
       const read = ctx.tasks.read(id, exec.agent)
-      const body = read.text.length > 0 ? read.text : '(no new output)'
-      const separator = body.endsWith('\n') ? '' : '\n'
-      return [{ type: 'text', text: `${body}${separator}${statusLine(read.snapshot)}` }]
+      return { text: read.text, task: publicTask(read.snapshot) }
     },
     presentCall: args => presentTaskCall(`Read output from background task ${args.task_id}`, 'read', args.task_id),
   }))
@@ -116,12 +172,18 @@ export function apply(ctx: Context, config: Config): void {
     name: 'task_list',
     description: 'List your background tasks (running and finished) with their ids, kinds, and statuses.',
     parameters: {},
+    output: {
+      schema: { type: 'array', items: PUBLIC_TASK_SCHEMA },
+      render: (_args, tasks) => [{
+        type: 'text',
+        text: tasks.length === 0
+          ? '(no background tasks)'
+          : tasks.map(t => `${t.id} [${t.kind}] ${t.status} — ${t.label}`).join('\n'),
+      }],
+    },
     execute(_args, exec) {
       const tasks = ctx.tasks.list(exec.agent)
-      const text = tasks.length === 0
-        ? '(no background tasks)'
-        : tasks.map(t => `${t.id} [${t.kind}] ${t.status} — ${t.label}`).join('\n')
-      return Promise.resolve([{ type: 'text', text }])
+      return Promise.resolve(tasks.map(publicTask))
     },
     presentCall: () => presentTaskCall('List background tasks', 'read'),
   }))
@@ -133,15 +195,35 @@ export function apply(ctx: Context, config: Config): void {
       task_id: { type: 'string', required: true, description: 'Task id returned by the tool that started the background work.' },
       reason: { type: 'string', description: 'Optional short reason, recorded in the log and forwarded to the task.' },
     },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          outcome: {
+            type: 'string',
+            required: true,
+            enum: ['cancellation-requested', 'already-finished'],
+          },
+          task: { ...PUBLIC_TASK_SCHEMA, required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.outcome === 'already-finished'
+          ? `task ${value.task.id} had already finished ${statusLine(value.task)}`
+          : `requested cancellation of task ${value.task.id}`,
+      }],
+    },
     execute(args, exec) {
       const id = validateTaskId(args.task_id)
       const result = ctx.tasks.kill(id, exec.agent, args.reason)
-      if (result === 'already-finished') {
-        // A snapshot describes terminal state without consuming pending output.
-        const snapshot = ctx.tasks.get(id, exec.agent)
-        return Promise.resolve([{ type: 'text', text: `task ${id} had already finished ${statusLine(snapshot)}` }])
-      }
-      return Promise.resolve([{ type: 'text', text: `requested cancellation of task ${id}` }])
+      // A snapshot describes current state without consuming pending output.
+      const snapshot = publicTask(ctx.tasks.get(id, exec.agent))
+      return Promise.resolve({
+        outcome: result === 'already-finished' ? 'already-finished' as const : 'cancellation-requested' as const,
+        task: snapshot,
+      })
     },
     presentCall: args => presentTaskCall(`Kill background task ${args.task_id}`, 'execute', args.task_id),
   }))