@zooid/core 0.12.0 → 0.14.0

package/src/config.ts

@@ -4,6 +4,7 @@ import { parse } from 'yaml'
 import type { AcpAgentSpec } from './acp-types.js'
 import { isPreset } from '@zooid/acp-client'
 import { interpolateEnv, interpolateString } from './env-interpolation.js'
+import { compileMatch } from './match-expression.js'
 import type {
   AgentConfig,
   CliFlags,
@@ -15,10 +16,15 @@ import type {
   MountConfig,
   RoomBinding,
   TransportConfig,
+  TriggerConfig,
+  TriggerMessage,
+  WebhookTriggerConfig,
   ZooidConfig,
   ZooidContainerConfig,
 } from './types.js'
 
+const WEBHOOK_PROVIDERS = ['github', 'stripe', 'slack', 'standard', 'custom'] as const
+
 const SLUG_RE = /^[a-z0-9-]+$/
 
 export interface LoadZooidConfigOptions {
@@ -29,6 +35,13 @@ export interface LoadZooidConfigOptions {
    * path.
    */
   configDir?: string
+  /**
+   * Cron-expression validator, called as `validateCron(name, expr)` and
+   * expected to throw on an invalid expression. `core` takes no cron
+   * dependency — `cli` passes croner's parser at load time. Defaults to a
+   * field-count check sufficient to catch malformed input at parse time.
+   */
+  validateCron?: (name: string, expr: string) => void
 }
 
 const AGENT_NAME_RE = /^[a-z][a-z0-9-]{0,31}$/
@@ -790,6 +803,297 @@ function parseAgents(
   return result
 }
 
+function defaultValidateCron(name: string, expr: string): void {
+  const parts = expr.trim().split(/\s+/)
+  if (parts.length < 5 || parts.length > 7) {
+    throw new Error(
+      `triggers.${name}.schedule: invalid cron expression ${JSON.stringify(expr)}`,
+    )
+  }
+}
+
+/**
+ * Expand a trigger's `as:` to a full MXID. Mirrors the explicit-`user_id`
+ * path in `parseTransportBinding`: a value already containing `:` is used
+ * as given (and validated); a bare localpart (`cron` or `@cron`) gets
+ * `:<server>` appended from the workforce's sole matrix transport. Unlike
+ * the *default* user_id (omitted case), this never auto-prefixes a
+ * workstation — an explicit value is used as written, so a
+ * workstation-scoped bot is written explicitly (`as: myworkstation.cron`).
+ */
+function expandTriggerAs(
+  name: string,
+  as: string,
+  transports: Record<string, TransportConfig>,
+): string {
+  if (as.includes(':')) {
+    if (!MATRIX_USER_ID_RE.test(as)) {
+      throw new Error(`triggers.${name}.as: must be a full MXID (got ${JSON.stringify(as)})`)
+    }
+    return as
+  }
+  const bare = as.startsWith('@') ? as : `@${as}`
+  if (!MATRIX_USER_LOCALPART_RE.test(bare)) {
+    throw new Error(`triggers.${name}.as: must be a full MXID (got ${JSON.stringify(as)})`)
+  }
+  const matrixTransports = Object.values(transports).filter(
+    (t): t is MatrixTransportConfig => t.type === 'matrix',
+  )
+  if (matrixTransports.length !== 1) {
+    throw new Error(
+      `triggers.${name}.as: "${as}" is a bare localpart, which requires exactly one matrix ` +
+        `transport to expand against (found ${matrixTransports.length}). Use a full MXID instead.`,
+    )
+  }
+  const serverName = deriveServerName(matrixTransports[0]!.user_namespace)
+  return `${bare}:${serverName}`
+}
+
+function parseTriggers(
+  raw: unknown,
+  agents: Record<string, AgentConfig>,
+  transports: Record<string, TransportConfig>,
+  validateCron: (name: string, expr: string) => void,
+  processEnv: NodeJS.ProcessEnv,
+  configDir: string | undefined,
+): Record<string, TriggerConfig> {
+  if (raw === undefined || raw === null) return {}
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error('triggers: must be a mapping')
+  }
+  const result: Record<string, TriggerConfig> = {}
+  for (const [name, val] of Object.entries(raw as Record<string, unknown>)) {
+    if (!val || typeof val !== 'object' || Array.isArray(val)) {
+      throw new Error(`triggers.${name} must be a mapping`)
+    }
+    const t = val as Record<string, unknown>
+
+    if (t.run !== undefined) {
+      throw new Error(
+        `triggers.${name}.run: is not supported — a trigger posts a message and the ` +
+          `agent runs what needs running. See [ZOD081] §Concept.`,
+      )
+    }
+
+    if (t.schedule === undefined && t.webhook === undefined) {
+      throw new Error(`triggers.${name}: must specify schedule: or webhook:`)
+    }
+    if (t.schedule !== undefined && t.webhook !== undefined) {
+      throw new Error(`triggers.${name}: specify either schedule: or webhook:, not both`)
+    }
+
+    let schedule: string | undefined
+    if (t.schedule !== undefined) {
+      if (typeof t.schedule !== 'string' || t.schedule.length === 0) {
+        throw new Error(`triggers.${name}.schedule: must be a non-empty string`)
+      }
+      validateCron(name, t.schedule)
+      schedule = t.schedule
+    }
+
+    let webhook: WebhookTriggerConfig | undefined
+    if (t.webhook !== undefined) {
+      webhook = parseWebhookTrigger(name, t.webhook, processEnv, configDir)
+    }
+
+    if (typeof t.as !== 'string' || t.as.length === 0) {
+      throw new Error(`triggers.${name}.as: must be a non-empty string`)
+    }
+    const as = expandTriggerAs(name, t.as, transports)
+
+    const hasFlat = t.room !== undefined || t.mention !== undefined || t.text !== undefined ||
+      t.match !== undefined
+    const hasMessages = t.messages !== undefined
+    if (hasFlat && hasMessages) {
+      throw new Error(
+        `triggers.${name}: specify either room:/mention:/text: or messages:, not both`,
+      )
+    }
+    if (!hasFlat && !hasMessages) {
+      throw new Error(`triggers.${name}: must specify room:/mention:/text: or messages:`)
+    }
+
+    let rawMessages: unknown[]
+    if (hasFlat) {
+      // Only a flat trigger's own top-level `match:` gets this unindexed
+      // name — once desugared, per-entry validation always speaks in terms
+      // of `messages[i]`, whether the entry came from `flat` or `messages:`.
+      if (t.match !== undefined && !webhook) {
+        throw new Error(`triggers.${name}.match: only applies to a webhook: trigger`)
+      }
+      rawMessages = [{ room: t.room, mention: t.mention, text: t.text, match: t.match }]
+    } else {
+      if (!Array.isArray(t.messages)) {
+        throw new Error(`triggers.${name}.messages: must be a list`)
+      }
+      if (t.messages.length === 0) {
+        throw new Error(`triggers.${name}.messages: must not be empty`)
+      }
+      rawMessages = t.messages
+    }
+
+    const messages = rawMessages.map((m, i) =>
+      parseTriggerMessage(name, i, m, agents, as, !!webhook),
+    )
+
+    const entry: TriggerConfig = { as, messages }
+    if (schedule !== undefined) entry.schedule = schedule
+    if (webhook !== undefined) entry.webhook = webhook
+    result[name] = entry
+  }
+  return result
+}
+
+/**
+ * Parse and validate one entry of `messages:` (or the single entry a flat
+ * trigger desugars into). Indexed error names (`triggers.<name>.messages[i]`)
+ * apply uniformly here regardless of which spelling produced the entry —
+ * only the flat-level `match:` presence check (in `parseTriggers`) still
+ * speaks in the unindexed, trigger-level name.
+ */
+function parseTriggerMessage(
+  name: string,
+  index: number,
+  raw: unknown,
+  agents: Record<string, AgentConfig>,
+  as: string,
+  hasWebhook: boolean,
+): TriggerMessage {
+  const label = `triggers.${name}.messages[${index}]`
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${label}: must be a mapping`)
+  }
+  const m = raw as Record<string, unknown>
+
+  if (typeof m.room !== 'string' || m.room.length === 0) {
+    throw new Error(`${label}.room: must be a non-empty string`)
+  }
+  if (!MATRIX_ROOM_IDENT_RE.test(m.room)) {
+    throw new Error(`${label}.room: must start with '#' or '!' (got ${JSON.stringify(m.room)})`)
+  }
+
+  if (typeof m.mention !== 'string' || m.mention.length === 0) {
+    throw new Error(`${label}.mention: must be a non-empty string`)
+  }
+  const mentionedAgent = agents[m.mention]
+  if (!mentionedAgent) {
+    throw new Error(`${label}.mention: unknown agent "${m.mention}"`)
+  }
+  if (!mentionedAgent.matrix) {
+    throw new Error(
+      `${label}.mention: agent "${m.mention}" has no matrix: binding — a trigger posts ` +
+        `through Matrix, so the mentioned agent must be matrix-bound.`,
+    )
+  }
+  // router.ts never routes an event back to its own sender
+  // (`event.sender === a.userId` short-circuits the match), so a trigger
+  // that posts as the very agent it mentions would silently never wake it.
+  if (as === mentionedAgent.matrix.user_id) {
+    throw new Error(
+      `triggers.${name}.as: must not equal the mentioned agent's own MXID (${as}) — a message ` +
+        `an agent sends never routes back to itself, so this trigger would silently never wake ` +
+        `"${m.mention}". Post as a different identity (a dedicated bot, or another agent's).`,
+    )
+  }
+
+  if (typeof m.text !== 'string' || m.text.length === 0) {
+    throw new Error(`${label}.text: must be a non-empty string`)
+  }
+
+  const message: TriggerMessage = { room: m.room, mention: m.mention, text: m.text }
+
+  if (m.match !== undefined) {
+    if (typeof m.match !== 'string' || m.match.length === 0) {
+      throw new Error(`${label}.match: must be a non-empty string`)
+    }
+    if (!hasWebhook) {
+      throw new Error(`${label}.match: only applies to a webhook: trigger`)
+    }
+    try {
+      message.match = compileMatch(m.match)
+    } catch (err) {
+      throw new Error(`${label}.match: ${(err as Error).message}`)
+    }
+  }
+
+  return message
+}
+
+/**
+ * Parse and validate a `webhook:` block. The secret is interpolated through
+ * `interpolateString` (not `interpolateEnv`'s deny-listed map form) — it is a
+ * single scalar value, and `ZOOID_*` references are legitimate here just as
+ * they are for a transport's `as_token` — [[ZOD082]] §Design 4, Secrets.
+ */
+function parseWebhookTrigger(
+  name: string,
+  raw: unknown,
+  processEnv: NodeJS.ProcessEnv,
+  configDir: string | undefined,
+): WebhookTriggerConfig {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    throw new Error(`triggers.${name}.webhook: must be a mapping`)
+  }
+  const w = raw as Record<string, unknown>
+
+  if (typeof w.provider !== 'string' || w.provider.length === 0) {
+    throw new Error(`triggers.${name}.webhook.provider: must be a non-empty string`)
+  }
+  if (!(WEBHOOK_PROVIDERS as readonly string[]).includes(w.provider)) {
+    throw new Error(
+      `triggers.${name}.webhook.provider: unknown provider ${JSON.stringify(w.provider)} ` +
+        `(expected one of: ${WEBHOOK_PROVIDERS.join(', ')})`,
+    )
+  }
+  const provider = w.provider as WebhookTriggerConfig['provider']
+
+  if (w.event !== undefined) {
+    throw new Error(`triggers.${name}.webhook.event: no longer supported — use match:`)
+  }
+
+  if (typeof w.secret !== 'string' || w.secret.length === 0) {
+    throw new Error(`triggers.${name}.webhook.secret: is required`)
+  }
+  const secret = interpolateString(w.secret, processEnv)
+
+  const config: WebhookTriggerConfig = { provider, secret }
+
+  if (provider !== 'custom') {
+    // Silently ignoring this would leave an operator believing they had
+    // configured a verifier that never ran.
+    if (w.verify !== undefined) {
+      throw new Error(
+        `triggers.${name}.webhook.verify: only applies to provider: custom ` +
+          `(this trigger uses provider: ${provider}, whose signing scheme is built in)`,
+      )
+    }
+    return config
+  }
+
+  // provider: custom — verification is a function the operator supplies,
+  // since no set of declarative fields covers every scheme (ed25519, SHA-1
+  // over sorted params, bespoke timestamped base strings). Resolved here;
+  // the daemon imports it at startup so a bad path fails fast.
+  if (typeof w.verify !== 'string' || w.verify.length === 0) {
+    throw new Error(
+      `triggers.${name}.webhook.verify: is required when provider: custom ` +
+        `(path to a module exporting the verifier function)`,
+    )
+  }
+  if (isAbsolute(w.verify)) {
+    config.verify = w.verify
+  } else if (!configDir) {
+    throw new Error(
+      `triggers.${name}.webhook.verify: relative path ${JSON.stringify(w.verify)} requires ` +
+        `configDir (zooid.yaml directory) — pass it via loadZooidConfig(yaml, { configDir })`,
+    )
+  } else {
+    config.verify = pathResolve(configDir, w.verify)
+  }
+
+  return config
+}
+
 function parseRuntime(raw: unknown): 'local' | 'docker' | 'podman' {
   const runtime = raw ?? 'docker'
   if (runtime !== 'local' && runtime !== 'docker' && runtime !== 'podman') {
@@ -860,12 +1164,21 @@ export function loadZooidConfig(
   const transports = parseTransports(r.transports, processEnv, workstation)
   const hooks = zooidHooks(r)
   const agents = parseAgents(r.agents, runtime, transports, hooks, processEnv, opts.configDir)
+  const triggers = parseTriggers(
+    r.triggers,
+    agents,
+    transports,
+    opts.validateCron ?? defaultValidateCron,
+    processEnv,
+    opts.configDir,
+  )
 
   const cfg: ZooidConfig = {
     runtime,
     transports,
     agents,
     hooks,
+    triggers,
   }
   if (workstation !== undefined) cfg.workstation = workstation
   if (r.container !== undefined && r.container !== null) {
@@ -955,6 +1268,7 @@ export function mergeCliFlags(base: ZooidConfig, flags: CliFlags): ZooidConfig {
     transports: base.transports,
     agents: base.agents,
     hooks: { ...base.hooks },
+    triggers: base.triggers,
   }
   if (runtime === 'docker' || runtime === 'podman') {
     const image = flags.image ?? base.container?.image

package/src/index.ts

@@ -7,10 +7,10 @@ export {
   findConfigFile,
 } from './config.js'
 export type { LoadZooidConfigOptions } from './config.js'
-export {
-  AcpAgentRegistry,
-  resolveAcpAgentSpec,
-} from './acp-registry.js'
+export { renderTemplate } from './render-template.js'
+export { compileMatch, evaluateMatch } from './match-expression.js'
+export type { MatchContext } from './match-expression.js'
+export { AcpAgentRegistry, resolveAcpAgentSpec } from './acp-registry.js'
 export {
   ApprovalCorrelator,
   type RegisteredApproval,
@@ -24,12 +24,7 @@ export type {
   ContextSpawnFactory,
 } from './acp-registry.js'
 export type { TapEvent } from '@zooid/acp-client'
-export type {
-  AcpAgentSpec,
-  AcpMount,
-  AcpRuntime,
-  AcpSpawnSpec,
-} from './acp-types.js'
+export type { AcpAgentSpec, AcpMount, AcpRuntime, AcpSpawnSpec } from './acp-types.js'
 export type {
   AgentConfig,
   ContainerConfig,
@@ -46,14 +41,20 @@ export type {
   Transport,
   InboundMessage,
   ThreadRef,
+  TriggerConfig,
+  TriggerMessage,
+  WebhookTriggerConfig,
 } from './types.js'
 export type {
   HistoryOptions,
   HistoryPage,
   Message,
   Member,
-  ChannelInfo,
+  RoomInfo,
+  SendMessageInput,
+  SendMessageResult,
   ThreadOverview,
   ThreadOverviewPage,
   TransportContextProvider,
 } from './transport-context.js'
+export * from './task-actions.js'

package/src/match-expression.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest'
+import { compileMatch, evaluateMatch } from './match-expression.js'
+
+const body = {
+  action: 'closed',
+  number: 42,
+  pull_request: { merged: true },
+  repository: { full_name: 'zooid-ai/zooid' },
+}
+const ctx = { event: 'pull_request', body, headers: { 'x-github-event': 'pull_request' }, output: '{}' }
+
+describe('evaluateMatch', () => {
+  it('is true when the predicate holds', () => {
+    expect(
+      evaluateMatch(compileMatch('event == "pull_request" && body.action == "closed" && body.pull_request.merged'), ctx),
+    ).toBe(true)
+  })
+
+  it('is false when the predicate does not hold', () => {
+    expect(evaluateMatch(compileMatch('body.action == "opened"'), ctx)).toBe(false)
+  })
+
+  it('reads headers', () => {
+    expect(evaluateMatch(compileMatch('headers["x-github-event"] == "pull_request"'), ctx)).toBe(true)
+  })
+
+  // The library returns a CelError value for a missing field rather than
+  // throwing or returning false. A merged-PR filter therefore errors on every
+  // issues delivery, which is ordinary and must read as "no match".
+  it('treats a missing field as no match, not an error and not a fire', () => {
+    const m = compileMatch('body.pull_request.merged')
+    expect(evaluateMatch(m, { ...ctx, body: { action: 'opened' } })).toBe(false)
+  })
+
+  it('supports has() so an operator can guard explicitly', () => {
+    const m = compileMatch('has(body.pull_request) && body.pull_request.merged')
+    expect(evaluateMatch(m, { ...ctx, body: { action: 'opened' } })).toBe(false)
+    expect(evaluateMatch(m, ctx)).toBe(true)
+  })
+
+  // Fail closed: only an actual boolean true fires. A non-boolean result must
+  // never be coerced.
+  it('does not fire on a truthy non-boolean result', () => {
+    expect(evaluateMatch(compileMatch('body.action'), ctx)).toBe(false)
+    expect(evaluateMatch(compileMatch('body.number'), ctx)).toBe(false)
+  })
+
+  it('does not fire on an undeclared variable', () => {
+    expect(evaluateMatch(compileMatch('nosuchthing == 1'), ctx)).toBe(false)
+  })
+})
+
+describe('compileMatch', () => {
+  it('rejects a syntax error at compile time, so a typo fails the daemon at boot', () => {
+    expect(() => compileMatch('body.action ==')).toThrow()
+  })
+
+  it('accepts a valid expression', () => {
+    expect(() => compileMatch('body.action == "opened"')).not.toThrow()
+  })
+})

package/src/match-expression.ts

@@ -0,0 +1,33 @@
+import { parse, run, type CelInput } from '@bufbuild/cel'
+
+export interface MatchContext {
+  event: string | undefined
+  body: unknown
+  headers: Record<string, string>
+  output: string
+}
+
+/** Parse-check an expression. Throws on a syntax error, so a typo fails at config load. */
+export function compileMatch(expr: string): string {
+  parse(expr)
+  return expr
+}
+
+/**
+ * Only an actual `true` fires. Everything else is "no match":
+ * - a CelError value (missing field, undeclared variable) — the library
+ *   returns these rather than throwing, and a merged-PR filter legitimately
+ *   errors on every issues delivery;
+ * - a truthy non-boolean (a string, a number), which must never be coerced;
+ * - a throw.
+ * Failing closed matters more here than anywhere else in the ingress: this is
+ * the only place an operator's typo could otherwise open a filter.
+ */
+export function evaluateMatch(expr: string, ctx: MatchContext): boolean {
+  try {
+    const result = run(expr, { ...ctx } as Record<string, CelInput>)
+    return result === true
+  } catch {
+    return false
+  }
+}

package/src/render-template.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest'
+import { renderTemplate } from './render-template.js'
+
+const ctx = {
+  event: 'issues',
+  body: { issue: { number: 23 }, repository: { full_name: 'zooid-ai/zooid' } },
+  headers: {},
+  output: '{\n  "issue": {}\n}',
+}
+
+describe('renderTemplate', () => {
+  it('interpolates an expression', () => {
+    expect(renderTemplate('Triage ${body.repository.full_name}#${body.issue.number}.', ctx)).toBe(
+      'Triage zooid-ai/zooid#23.',
+    )
+  })
+
+  it('leaves text with no placeholders alone', () => {
+    expect(renderTemplate('A PR merged.', ctx)).toBe('A PR merged.')
+  })
+
+  // ${output} is not a special case: it is a bound variable like any other, so
+  // a whole-payload dump still works for senders we control ([[ZOD081]] §2).
+  it('still supports ${output}', () => {
+    expect(renderTemplate('Payload:\n${output}', ctx)).toContain('"issue"')
+  })
+
+  // A bad placeholder must not take the message down, and must not silently
+  // paste an error object into a room.
+  it('renders an unresolvable placeholder as empty rather than throwing', () => {
+    expect(renderTemplate('x${body.nope.deep}y', ctx)).toBe('xy')
+  })
+
+  it('does not re-scan substituted content, so a payload cannot inject a placeholder', () => {
+    const evil = { ...ctx, body: { title: '${body.secret}' }, }
+    expect(renderTemplate('${body.title}', evil)).toBe('${body.secret}')
+  })
+})

package/src/render-template.ts

@@ -0,0 +1,32 @@
+import { run, isCelError, type CelInput } from '@bufbuild/cel'
+import type { MatchContext } from './match-expression.js'
+
+// Non-greedy so `${a}...${b}` is two placeholders, not one spanning both.
+const PLACEHOLDER_RE = /\$\{([\s\S]+?)\}/g
+
+/**
+ * Fill `${...}` placeholders in a trigger's `text:`. Each placeholder is a
+ * CEL expression over the same bindings `match:` sees — one expression
+ * language, not two. `${output}` is not a special case: `output` is just
+ * another bound variable, so a whole-payload dump still works for senders we
+ * control ([[ZOD081]] §2).
+ *
+ * An unresolvable placeholder (missing field, bad expression) renders as
+ * empty rather than throwing or pasting an error object into a room — a bad
+ * placeholder must not take the message down.
+ *
+ * The result is never re-scanned, so a payload that itself contains the
+ * literal string `${...}` cannot inject a placeholder.
+ */
+export function renderTemplate(template: string, ctx: MatchContext): string {
+  return template.replace(PLACEHOLDER_RE, (_match, expr: string) => {
+    let result: unknown
+    try {
+      result = run(expr, { ...ctx } as Record<string, CelInput>)
+    } catch {
+      return ''
+    }
+    if (result === undefined || isCelError(result)) return ''
+    return String(result)
+  })
+}

package/src/task-actions.ts

@@ -0,0 +1,84 @@
+/** Harness-independent delegated-task contracts ([[ZOD072]]). */
+export interface TaskCallerRef {
+  agentName: string
+  channelId: string
+  threadRoot: string
+  sessionKey: string
+}
+export interface StartTaskSpec {
+  agent: string
+  prompt: string
+}
+export interface StartTasksInput {
+  tasks: StartTaskSpec[]
+  notify?: 'caller' | 'none'
+}
+export type StartTaskResult =
+  | { agent: string; status: 'started'; thread_id: string }
+  | {
+      agent: string
+      status: 'refused' | 'failed'
+      reason: string
+      attempt_id?: string
+    }
+export interface StartTasksOutput {
+  results: StartTaskResult[]
+  notify: 'caller' | 'none'
+  /** Stated at the point of decision, where the model actually reads it. */
+  delivery: string
+}
+export interface CompleteTaskInput {
+  summary: string
+}
+export interface CompleteTaskOutput {
+  status: 'recorded' | 'already_recorded' | 'refused'
+  reason?: string
+}
+/** What this session is, so the surface can gate itself instead of refusing later. */
+export interface TaskRole {
+  is_task_assignee: boolean
+  can_start_task_threads: boolean
+}
+export interface TaskActions {
+  startTasks(caller: TaskCallerRef, input: StartTasksInput): Promise<StartTasksOutput>
+  completeTask(caller: TaskCallerRef, input: CompleteTaskInput): Promise<CompleteTaskOutput>
+  describeRole(caller: TaskCallerRef): Promise<TaskRole>
+}
+/** One in-thread handoff inside a delegated task. */
+export type InvocationState = 'outstanding' | 'returned' | 'cancelled'
+export interface InvocationRecord {
+  invocationId: string
+  taskId: string
+  callerAgent: string
+  callerSessionKey: string
+  calleeAgent: string
+  callEventId?: string
+  calleeSessionKey?: string
+  state: InvocationState
+}
+/** Open human-input requests for a session. ZOD078 supplies the implementation. */
+export interface PendingInputRegistry {
+  countFor(sessionKey: string): number
+  cancelFor(sessionKeys: string[]): void
+}
+export const NO_PENDING_INPUT: PendingInputRegistry = {
+  countFor: () => 0,
+  cancelFor: () => {},
+}
+export const THREAD_START_FIELD = 'dev.zooid.thread_start'
+export const THREAD_RESULT_FIELD = 'dev.zooid.thread_result'
+export interface ThreadStartContent {
+  version: 1
+  assignee: string
+  attempt_id: string
+  parent: { agent: string; thread_root: string; session_key: string }
+  notify: 'caller' | 'none'
+}
+export interface ThreadCompletion {
+  agent: string
+  thread_id: string
+  status: 'complete' | 'failed' | 'cancelled' | 'partial'
+  output?: { type: 'message'; text: string }
+  reason?: string
+  error?: string
+}