@alvin0/ai-agent-sdk-core 0.1.0

package/dist/agent/memory/memory.js

@@ -0,0 +1,5 @@
+const e=Object.freeze({objective:0,constraint:1,decision:2,"next-step":3,progress:4,fact:5});var t=class t{records=new Map;limits;nextId=1;storedChars=0;constructor(e=[],t={}){this.limits=i(t);for(let t of e)this.remember(t)}static fromSnapshot(e,n={}){if(typeof e!=`object`||!e||e.version!==1||!Array.isArray(e.items))throw TypeError(`unsupported agent memory snapshot`);let r=new t([],n);if(e.items.length>r.limits.maxItems)throw RangeError(`agent memory snapshot exceeds the ${r.limits.maxItems}-item limit`);for(let t of e.items){if(o(t),r.records.has(t.id))throw TypeError(`duplicate agent memory id '${t.id}'`);if(t.content.length>r.limits.maxItemChars)throw RangeError(`agent memory item '${t.id}' exceeds the ${r.limits.maxItemChars}-character limit`);if(r.storedChars+t.content.length>r.limits.maxStoredChars)throw RangeError(`agent memory snapshot exceeds the ${r.limits.maxStoredChars}-character limit`);r.records.set(t.id,Object.freeze({id:t.id,kind:t.kind,content:t.content,createdAt:t.createdAt,updatedAt:t.updatedAt})),r.storedChars+=t.content.length;let e=c(t.id);e!==void 0&&(r.nextId=Math.max(r.nextId,e))}return r}remember(e){r(e);let t=e.id??`memory-${this.nextId}`,n=e.content.trim();if(n.length>this.limits.maxItemChars)throw RangeError(`agent memory item '${t}' exceeds the ${this.limits.maxItemChars}-character limit`);let i=c(t),a=this.records.get(t);if(a===void 0&&this.records.size>=this.limits.maxItems)throw RangeError(`agent memory reached its ${this.limits.maxItems}-item limit`);let o=this.storedChars-(a?.content.length??0)+n.length;if(o>this.limits.maxStoredChars)throw RangeError(`agent memory reached its ${this.limits.maxStoredChars}-character limit`);let s=new Date().toISOString(),l=Object.freeze({id:t,kind:e.kind,content:n,createdAt:a?.createdAt??s,updatedAt:s});return this.records.set(t,l),this.storedChars=o,i!==void 0&&(this.nextId=Math.max(this.nextId,i)),l}forget(e){let t=this.records.get(e);return t!==void 0&&(this.records.delete(e),this.storedChars-=t.content.length,!0)}items(){return Object.freeze([...this.records.values()])}snapshot(){return Object.freeze({version:1,items:Object.freeze(this.items().map(e=>Object.freeze(structuredClone(e))))})}captureOriginalObjective(e){if([...this.records.values()].some(e=>e.kind===`objective`))return;let t=l(e,this.limits.maxItemChars).trim();return this.remember({id:`original-objective`,kind:`objective`,content:t.length>0?t:`[The original request contained non-text input.]`})}render(t=12e3){if(!Number.isInteger(t)||t<256)throw RangeError(`agent memory render maxChars must be an integer >= 256`);let n=[...this.records.values()].sort((t,n)=>e[t.kind]-e[n.kind]||t.createdAt.localeCompare(n.createdAt));if(n.length===0)return``;let r=[`<task-memory>`,`Durable task facts follow. Preserve the original objective and obey active constraints even when older conversation turns were compacted.`],i=t-r.join(`
+`).length-14-2,a=[];for(let e of n){if(i<=0)break;let t=`- ${e.kind} [${e.id}]: `,n=Math.max(0,i-t.length-1),r=t+u(JSON.stringify(e.content),n);a.push(r),i-=r.length+1}return[...r,...a,`</task-memory>`].join(`
+`)}};function n(e){let t=e?.maxInjectedChars??12e3;if(!Number.isInteger(t)||t<256)throw RangeError(`agent memory maxInjectedChars must be an integer >= 256`);let n=i(e??{}),a=new Set,o=1,s=0,l=Object.freeze([...e?.seed??[]].map(e=>{r(e);let t=e.id??`memory-${o++}`,i=c(t);if(i!==void 0&&(o=Math.max(o,i)),a.has(t))throw TypeError(`duplicate agent memory seed id '${t}'`);a.add(t);let l=e.content.trim().length;if(l>n.maxItemChars)throw RangeError(`agent memory seed '${t}' exceeds the ${n.maxItemChars}-character limit`);if(s+=l,s>n.maxStoredChars)throw RangeError(`agent memory seed exceeds the ${n.maxStoredChars}-character limit`);return Object.freeze({...e.id===void 0?{}:{id:e.id},kind:e.kind,content:e.content})}));if(l.length>n.maxItems)throw RangeError(`agent memory seed exceeds the ${n.maxItems}-item limit`);return Object.freeze({autoCaptureObjective:e?.autoCaptureObjective??!0,maxInjectedChars:t,...n,seed:l})}function r(t){if(t.id!==void 0&&(typeof t.id!=`string`||t.id.trim().length===0||t.id.length>256||/\s/.test(t.id)))throw TypeError(`agent memory id must be non-empty, at most 256 characters, and contain no whitespace`);if(!Object.hasOwn(e,t.kind))throw TypeError(`unsupported agent memory kind '${String(t.kind)}'`);if(typeof t.content!=`string`||t.content.trim().length===0)throw TypeError(`agent memory content must be a non-empty string`)}function i(e){let t=a(e.maxItems??1024,`maxItems`),n=a(e.maxItemChars??65536,`maxItemChars`),r=a(e.maxStoredChars??1048576,`maxStoredChars`);if(n>r)throw RangeError(`agent memory maxItemChars must not exceed maxStoredChars`);return Object.freeze({maxItems:t,maxItemChars:n,maxStoredChars:r})}function a(e,t){if(!Number.isSafeInteger(e)||e<1)throw RangeError(`agent memory ${t} must be a positive safe integer`);return e}function o(e){if(r(e),!s(e.createdAt)||!s(e.updatedAt))throw TypeError(`agent memory timestamps must be bounded ISO date strings`)}function s(e){if(typeof e!=`string`||e.length===0||e.length>64)return!1;let t=Date.parse(e);if(!Number.isFinite(t))return!1;try{return new Date(t).toISOString()===e}catch{return!1}}function c(e){let t=/^memory-(\d+)$/.exec(e)?.[1];if(t===void 0)return;let n=Number(t);return Number.isSafeInteger(n)&&n>=1&&n<2**53-1?n+1:void 0}function l(e,t){let n=``,r=!1;for(let i of e.content){if(i.type!==`text`)continue;let e=n.length===0?``:`
+`,a=t-n.length;if(e.length+i.text.length<=a){n+=e+i.text;continue}let o=Math.max(0,a-e.length-22);n+=e+i.text.slice(0,o)+`…[objective truncated]`.slice(0,Math.max(0,a-e.length-o)),r=!0;break}return r?n.slice(0,t):n}function u(e,t){if(e.length<=t)return e;if(t<=1)return e.slice(0,t);let n=Math.ceil((t-1)/2),r=Math.floor((t-1)/2);return e.slice(0,n)+`…`+e.slice(e.length-r)}export{t as AgentMemory,n as resolveMemoryConfig};
+//# sourceMappingURL=memory.js.map

package/dist/agent/memory/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","names":[],"sources":["../../../src/agent/memory/memory.ts"],"sourcesContent":["/** Durable, explicitly inspectable task memory kept outside compactable history. */\n\nimport type { UserMessage } from '../../message/index.ts'\n\nexport type AgentMemoryKind =\n  | 'objective'\n  | 'constraint'\n  | 'decision'\n  | 'fact'\n  | 'progress'\n  | 'next-step'\n\nexport interface AgentMemorySeed {\n  readonly id?: string\n  readonly kind: AgentMemoryKind\n  readonly content: string\n}\n\nexport interface AgentMemoryItem {\n  readonly id: string\n  readonly kind: AgentMemoryKind\n  readonly content: string\n  readonly createdAt: string\n  readonly updatedAt: string\n}\n\nexport interface AgentMemorySnapshot {\n  readonly version: 1\n  readonly items: readonly AgentMemoryItem[]\n}\n\nexport interface AgentMemoryConfigInput {\n  /** Pin the first real user message as the original objective. Defaults to true. */\n  readonly autoCaptureObjective?: boolean\n  /** Maximum rendered memory characters injected into every model request. Defaults to 12,000. */\n  readonly maxInjectedChars?: number\n  /** Maximum retained memory records. Defaults to 1,024. */\n  readonly maxItems?: number\n  /** Maximum characters retained by one record. Defaults to 65,536. */\n  readonly maxItemChars?: number\n  /** Maximum cumulative retained content characters. Defaults to 1 MiB. */\n  readonly maxStoredChars?: number\n  readonly seed?: readonly AgentMemorySeed[]\n}\n\nexport interface AgentMemoryConfig {\n  readonly autoCaptureObjective: boolean\n  readonly maxInjectedChars: number\n  readonly maxItems: number\n  readonly maxItemChars: number\n  readonly maxStoredChars: number\n  readonly seed: readonly AgentMemorySeed[]\n}\n\nconst PRIORITY: Readonly<Record<AgentMemoryKind, number>> = Object.freeze({\n  objective: 0,\n  constraint: 1,\n  decision: 2,\n  'next-step': 3,\n  progress: 4,\n  fact: 5,\n})\n\nexport class AgentMemory {\n  private readonly records = new Map<string, AgentMemoryItem>()\n  private readonly limits: Pick<AgentMemoryConfig, 'maxItems' | 'maxItemChars' | 'maxStoredChars'>\n  private nextId = 1\n  private storedChars = 0\n\n  constructor(\n    seed: readonly AgentMemorySeed[] = [],\n    limits: Partial<Pick<AgentMemoryConfig, 'maxItems' | 'maxItemChars' | 'maxStoredChars'>> = {},\n  ) {\n    this.limits = resolveMemoryLimits(limits)\n    for (const item of seed) this.remember(item)\n  }\n\n  static fromSnapshot(\n    snapshot: AgentMemorySnapshot,\n    limits: Partial<Pick<AgentMemoryConfig, 'maxItems' | 'maxItemChars' | 'maxStoredChars'>> = {},\n  ): AgentMemory {\n    if (typeof snapshot !== 'object' || snapshot === null\n      || snapshot.version !== 1 || !Array.isArray(snapshot.items)) {\n      throw new TypeError('unsupported agent memory snapshot')\n    }\n    const memory = new AgentMemory([], limits)\n    if (snapshot.items.length > memory.limits.maxItems) {\n      throw new RangeError(`agent memory snapshot exceeds the ${memory.limits.maxItems}-item limit`)\n    }\n    for (const item of snapshot.items) {\n      validateItem(item)\n      if (memory.records.has(item.id)) throw new TypeError(`duplicate agent memory id '${item.id}'`)\n      if (item.content.length > memory.limits.maxItemChars) {\n        throw new RangeError(`agent memory item '${item.id}' exceeds the ${memory.limits.maxItemChars}-character limit`)\n      }\n      if (memory.storedChars + item.content.length > memory.limits.maxStoredChars) {\n        throw new RangeError(`agent memory snapshot exceeds the ${memory.limits.maxStoredChars}-character limit`)\n      }\n      memory.records.set(item.id, Object.freeze({\n        id: item.id,\n        kind: item.kind,\n        content: item.content,\n        createdAt: item.createdAt,\n        updatedAt: item.updatedAt,\n      }))\n      memory.storedChars += item.content.length\n      const successor = memoryIdSuccessor(item.id)\n      if (successor !== undefined) memory.nextId = Math.max(memory.nextId, successor)\n    }\n    return memory\n  }\n\n  /** Add or update one stable memory item. Supplying the same id is an upsert. */\n  remember(input: AgentMemorySeed): AgentMemoryItem {\n    validateSeed(input)\n    const id = input.id ?? `memory-${this.nextId}`\n    const content = input.content.trim()\n    if (content.length > this.limits.maxItemChars) {\n      throw new RangeError(`agent memory item '${id}' exceeds the ${this.limits.maxItemChars}-character limit`)\n    }\n    const successor = memoryIdSuccessor(id)\n    const previous = this.records.get(id)\n    if (previous === undefined && this.records.size >= this.limits.maxItems) {\n      throw new RangeError(`agent memory reached its ${this.limits.maxItems}-item limit`)\n    }\n    const nextStoredChars = this.storedChars - (previous?.content.length ?? 0) + content.length\n    if (nextStoredChars > this.limits.maxStoredChars) {\n      throw new RangeError(`agent memory reached its ${this.limits.maxStoredChars}-character limit`)\n    }\n    const at = new Date().toISOString()\n    const item = Object.freeze({\n      id,\n      kind: input.kind,\n      content,\n      createdAt: previous?.createdAt ?? at,\n      updatedAt: at,\n    })\n    this.records.set(id, item)\n    this.storedChars = nextStoredChars\n    if (successor !== undefined) this.nextId = Math.max(this.nextId, successor)\n    return item\n  }\n\n  forget(id: string): boolean {\n    const item = this.records.get(id)\n    if (item === undefined) return false\n    this.records.delete(id)\n    this.storedChars -= item.content.length\n    return true\n  }\n\n  items(): readonly AgentMemoryItem[] {\n    return Object.freeze([...this.records.values()])\n  }\n\n  snapshot(): AgentMemorySnapshot {\n    return Object.freeze({\n      version: 1,\n      items: Object.freeze(this.items().map(item => Object.freeze(structuredClone(item)))),\n    })\n  }\n\n  /** Capture the first user request verbatim enough to survive every later compaction. */\n  captureOriginalObjective(message: UserMessage): AgentMemoryItem | undefined {\n    if ([...this.records.values()].some(item => item.kind === 'objective')) return undefined\n    const text = collectTextPrefix(message, this.limits.maxItemChars).trim()\n    return this.remember({\n      id: 'original-objective',\n      kind: 'objective',\n      content: text.length > 0 ? text : '[The original request contained non-text input.]',\n    })\n  }\n\n  /** Render bounded pinned context, ordered by importance rather than insertion accident. */\n  render(maxChars = 12_000): string {\n    if (!Number.isInteger(maxChars) || maxChars < 256) {\n      throw new RangeError('agent memory render maxChars must be an integer >= 256')\n    }\n    const ordered = [...this.records.values()].sort((a, b) =>\n      PRIORITY[a.kind] - PRIORITY[b.kind] || a.createdAt.localeCompare(b.createdAt))\n    if (ordered.length === 0) return ''\n    const preamble = [\n      '<task-memory>',\n      'Durable task facts follow. Preserve the original objective and obey active constraints even when older conversation turns were compacted.',\n    ]\n    const closing = '</task-memory>'\n    let remaining = maxChars - preamble.join('\\n').length - closing.length - 2\n    const lines: string[] = []\n    for (const item of ordered) {\n      if (remaining <= 0) break\n      const prefix = `- ${item.kind} [${item.id}]: `\n      const contentBudget = Math.max(0, remaining - prefix.length - 1)\n      const content = truncateMiddle(JSON.stringify(item.content), contentBudget)\n      const line = prefix + content\n      lines.push(line)\n      remaining -= line.length + 1\n    }\n    return [...preamble, ...lines, closing].join('\\n')\n  }\n}\n\nexport function resolveMemoryConfig(input: AgentMemoryConfigInput | undefined): AgentMemoryConfig {\n  const maxInjectedChars = input?.maxInjectedChars ?? 12_000\n  if (!Number.isInteger(maxInjectedChars) || maxInjectedChars < 256) {\n    throw new RangeError('agent memory maxInjectedChars must be an integer >= 256')\n  }\n  const limits = resolveMemoryLimits(input ?? {})\n  const ids = new Set<string>()\n  let nextId = 1\n  let storedChars = 0\n  const seed = Object.freeze([...(input?.seed ?? [])].map(item => {\n    validateSeed(item)\n    const id = item.id ?? `memory-${nextId++}`\n    const successor = memoryIdSuccessor(id)\n    if (successor !== undefined) nextId = Math.max(nextId, successor)\n    if (ids.has(id)) throw new TypeError(`duplicate agent memory seed id '${id}'`)\n    ids.add(id)\n    const chars = item.content.trim().length\n    if (chars > limits.maxItemChars) {\n      throw new RangeError(`agent memory seed '${id}' exceeds the ${limits.maxItemChars}-character limit`)\n    }\n    storedChars += chars\n    if (storedChars > limits.maxStoredChars) {\n      throw new RangeError(`agent memory seed exceeds the ${limits.maxStoredChars}-character limit`)\n    }\n    return Object.freeze({\n      ...(item.id === undefined ? {} : { id: item.id }),\n      kind: item.kind,\n      content: item.content,\n    })\n  }))\n  if (seed.length > limits.maxItems) {\n    throw new RangeError(`agent memory seed exceeds the ${limits.maxItems}-item limit`)\n  }\n  return Object.freeze({\n    autoCaptureObjective: input?.autoCaptureObjective ?? true,\n    maxInjectedChars,\n    ...limits,\n    seed,\n  })\n}\n\nfunction validateSeed(input: AgentMemorySeed): void {\n  if (input.id !== undefined && (typeof input.id !== 'string'\n    || input.id.trim().length === 0 || input.id.length > 256 || /\\s/.test(input.id))) {\n    throw new TypeError('agent memory id must be non-empty, at most 256 characters, and contain no whitespace')\n  }\n  if (!Object.hasOwn(PRIORITY, input.kind)) throw new TypeError(`unsupported agent memory kind '${String(input.kind)}'`)\n  if (typeof input.content !== 'string' || input.content.trim().length === 0) {\n    throw new TypeError('agent memory content must be a non-empty string')\n  }\n}\n\nfunction resolveMemoryLimits(\n  input: Partial<Pick<AgentMemoryConfig, 'maxItems' | 'maxItemChars' | 'maxStoredChars'>>,\n): Pick<AgentMemoryConfig, 'maxItems' | 'maxItemChars' | 'maxStoredChars'> {\n  const maxItems = positiveInteger(input.maxItems ?? 1_024, 'maxItems')\n  const maxItemChars = positiveInteger(input.maxItemChars ?? 65_536, 'maxItemChars')\n  const maxStoredChars = positiveInteger(input.maxStoredChars ?? 1024 * 1024, 'maxStoredChars')\n  if (maxItemChars > maxStoredChars) {\n    throw new RangeError('agent memory maxItemChars must not exceed maxStoredChars')\n  }\n  return Object.freeze({ maxItems, maxItemChars, maxStoredChars })\n}\n\nfunction positiveInteger(value: number, name: string): number {\n  if (!Number.isSafeInteger(value) || value < 1) {\n    throw new RangeError(`agent memory ${name} must be a positive safe integer`)\n  }\n  return value\n}\n\nfunction validateItem(item: AgentMemoryItem): void {\n  validateSeed(item)\n  if (!validTimestamp(item.createdAt) || !validTimestamp(item.updatedAt)) {\n    throw new TypeError('agent memory timestamps must be bounded ISO date strings')\n  }\n}\n\nfunction validTimestamp(value: unknown): value is string {\n  if (typeof value !== 'string' || value.length === 0 || value.length > 64) return false\n  const parsed = Date.parse(value)\n  if (!Number.isFinite(parsed)) return false\n  try { return new Date(parsed).toISOString() === value } catch { return false }\n}\n\nfunction memoryIdSuccessor(id: string): number | undefined {\n  const suffix = /^memory-(\\d+)$/.exec(id)?.[1]\n  if (suffix === undefined) return undefined\n  const numeric = Number(suffix)\n  return Number.isSafeInteger(numeric) && numeric >= 1 && numeric < Number.MAX_SAFE_INTEGER\n    ? numeric + 1\n    : undefined\n}\n\nfunction collectTextPrefix(message: UserMessage, maxChars: number): string {\n  const marker = '…[objective truncated]'\n  let text = ''\n  let truncated = false\n  for (const block of message.content) {\n    if (block.type !== 'text') continue\n    const separator = text.length === 0 ? '' : '\\n'\n    const remaining = maxChars - text.length\n    if (separator.length + block.text.length <= remaining) {\n      text += separator + block.text\n      continue\n    }\n    const available = Math.max(0, remaining - separator.length - marker.length)\n    text += separator + block.text.slice(0, available) + marker.slice(0, Math.max(0, remaining - separator.length - available))\n    truncated = true\n    break\n  }\n  return truncated ? text.slice(0, maxChars) : text\n}\n\nfunction truncateMiddle(value: string, maxChars: number): string {\n  if (value.length <= maxChars) return value\n  if (maxChars <= 1) return value.slice(0, maxChars)\n  const marker = '…'\n  const head = Math.ceil((maxChars - marker.length) / 2)\n  const tail = Math.floor((maxChars - marker.length) / 2)\n  return value.slice(0, head) + marker + value.slice(value.length - tail)\n}\n"],"mappings":"AAsDA,MAAM,EAAsD,OAAO,OAAO,CACxE,UAAW,EACX,WAAY,EACZ,SAAU,EACV,YAAa,EACb,SAAU,EACV,KAAM,CACR,CAAC,EAED,IAAa,EAAb,MAAa,CAAY,CACvB,QAA2B,IAAI,IAC/B,OACA,OAAiB,EACjB,YAAsB,EAEtB,YACE,EAAmC,CAAC,EACpC,EAA2F,CAAC,EAC5F,CACA,KAAK,OAAS,EAAoB,CAAM,EACxC,IAAK,IAAM,KAAQ,EAAM,KAAK,SAAS,CAAI,CAC7C,CAEA,OAAO,aACL,EACA,EAA2F,CAAC,EAC/E,CACb,GAAI,OAAO,GAAa,WAAY,GAC/B,EAAS,UAAY,GAAK,CAAC,MAAM,QAAQ,EAAS,KAAK,EAC1D,MAAU,UAAU,mCAAmC,EAEzD,IAAM,EAAS,IAAI,EAAY,CAAC,EAAG,CAAM,EACzC,GAAI,EAAS,MAAM,OAAS,EAAO,OAAO,SACxC,MAAU,WAAW,qCAAqC,EAAO,OAAO,SAAS,YAAY,EAE/F,IAAK,IAAM,KAAQ,EAAS,MAAO,CAEjC,GADA,EAAa,CAAI,EACb,EAAO,QAAQ,IAAI,EAAK,EAAE,EAAG,MAAU,UAAU,8BAA8B,EAAK,GAAG,EAAE,EAC7F,GAAI,EAAK,QAAQ,OAAS,EAAO,OAAO,aACtC,MAAU,WAAW,sBAAsB,EAAK,GAAG,gBAAgB,EAAO,OAAO,aAAa,iBAAiB,EAEjH,GAAI,EAAO,YAAc,EAAK,QAAQ,OAAS,EAAO,OAAO,eAC3D,MAAU,WAAW,qCAAqC,EAAO,OAAO,eAAe,iBAAiB,EAE1G,EAAO,QAAQ,IAAI,EAAK,GAAI,OAAO,OAAO,CACxC,GAAI,EAAK,GACT,KAAM,EAAK,KACX,QAAS,EAAK,QACd,UAAW,EAAK,UAChB,UAAW,EAAK,SAClB,CAAC,CAAC,EACF,EAAO,aAAe,EAAK,QAAQ,OACnC,IAAM,EAAY,EAAkB,EAAK,EAAE,EACvC,IAAc,IAAA,KAAW,EAAO,OAAS,KAAK,IAAI,EAAO,OAAQ,CAAS,EAChF,CACA,OAAO,CACT,CAGA,SAAS,EAAyC,CAChD,EAAa,CAAK,EAClB,IAAM,EAAK,EAAM,IAAM,UAAU,KAAK,SAChC,EAAU,EAAM,QAAQ,KAAK,EACnC,GAAI,EAAQ,OAAS,KAAK,OAAO,aAC/B,MAAU,WAAW,sBAAsB,EAAG,gBAAgB,KAAK,OAAO,aAAa,iBAAiB,EAE1G,IAAM,EAAY,EAAkB,CAAE,EAChC,EAAW,KAAK,QAAQ,IAAI,CAAE,EACpC,GAAI,IAAa,IAAA,IAAa,KAAK,QAAQ,MAAQ,KAAK,OAAO,SAC7D,MAAU,WAAW,4BAA4B,KAAK,OAAO,SAAS,YAAY,EAEpF,IAAM,EAAkB,KAAK,aAAe,GAAU,QAAQ,QAAU,GAAK,EAAQ,OACrF,GAAI,EAAkB,KAAK,OAAO,eAChC,MAAU,WAAW,4BAA4B,KAAK,OAAO,eAAe,iBAAiB,EAE/F,IAAM,EAAK,IAAI,KAAK,CAAA,CAAE,YAAY,EAC5B,EAAO,OAAO,OAAO,CACzB,KACA,KAAM,EAAM,KACZ,UACA,UAAW,GAAU,WAAa,EAClC,UAAW,CACb,CAAC,EAID,OAHA,KAAK,QAAQ,IAAI,EAAI,CAAI,EACzB,KAAK,YAAc,EACf,IAAc,IAAA,KAAW,KAAK,OAAS,KAAK,IAAI,KAAK,OAAQ,CAAS,GACnE,CACT,CAEA,OAAO,EAAqB,CAC1B,IAAM,EAAO,KAAK,QAAQ,IAAI,CAAE,EAIhC,OAHI,IAAS,IAAA,KACb,KAAK,QAAQ,OAAO,CAAE,EACtB,KAAK,aAAe,EAAK,QAAQ,OAC1B,GACT,CAEA,OAAoC,CAClC,OAAO,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,OAAO,CAAC,CAAC,CACjD,CAEA,UAAgC,CAC9B,OAAO,OAAO,OAAO,CACnB,QAAS,EACT,MAAO,OAAO,OAAO,KAAK,MAAM,CAAC,CAAC,IAAI,GAAQ,OAAO,OAAO,gBAAgB,CAAI,CAAC,CAAC,CAAC,CACrF,CAAC,CACH,CAGA,yBAAyB,EAAmD,CAC1E,GAAI,CAAC,GAAG,KAAK,QAAQ,OAAO,CAAC,CAAC,CAAC,KAAK,GAAQ,EAAK,OAAS,WAAW,EAAG,OACxE,IAAM,EAAO,EAAkB,EAAS,KAAK,OAAO,YAAY,CAAC,CAAC,KAAK,EACvE,OAAO,KAAK,SAAS,CACnB,GAAI,qBACJ,KAAM,YACN,QAAS,EAAK,OAAS,EAAI,EAAO,kDACpC,CAAC,CACH,CAGA,OAAO,EAAW,KAAgB,CAChC,GAAI,CAAC,OAAO,UAAU,CAAQ,GAAK,EAAW,IAC5C,MAAU,WAAW,wDAAwD,EAE/E,IAAM,EAAU,CAAC,GAAG,KAAK,QAAQ,OAAO,CAAC,CAAC,CAAC,MAAM,EAAG,IAClD,EAAS,EAAE,MAAQ,EAAS,EAAE,OAAS,EAAE,UAAU,cAAc,EAAE,SAAS,CAAC,EAC/E,GAAI,EAAQ,SAAW,EAAG,MAAO,GACjC,IAAM,EAAW,CACf,gBACA,2IACF,EAEI,EAAY,EAAW,EAAS,KAAK;CAAI,CAAC,CAAC,OAAS,GAAiB,EACnE,EAAkB,CAAC,EACzB,IAAK,IAAM,KAAQ,EAAS,CAC1B,GAAI,GAAa,EAAG,MACpB,IAAM,EAAS,KAAK,EAAK,KAAK,IAAI,EAAK,GAAG,KACpC,EAAgB,KAAK,IAAI,EAAG,EAAY,EAAO,OAAS,CAAC,EAEzD,EAAO,EADG,EAAe,KAAK,UAAU,EAAK,OAAO,EAAG,CACjC,EAC5B,EAAM,KAAK,CAAI,EACf,GAAa,EAAK,OAAS,CAC7B,CACA,MAAO,CAAC,GAAG,EAAU,GAAG,EAAO,gBAAO,CAAC,CAAC,KAAK;CAAI,CACnD,CACF,EAEA,SAAgB,EAAoB,EAA8D,CAChG,IAAM,EAAmB,GAAO,kBAAoB,KACpD,GAAI,CAAC,OAAO,UAAU,CAAgB,GAAK,EAAmB,IAC5D,MAAU,WAAW,yDAAyD,EAEhF,IAAM,EAAS,EAAoB,GAAS,CAAC,CAAC,EACxC,EAAM,IAAI,IACZ,EAAS,EACT,EAAc,EACZ,EAAO,OAAO,OAAO,CAAC,GAAI,GAAO,MAAQ,CAAC,CAAE,CAAC,CAAC,IAAI,GAAQ,CAC9D,EAAa,CAAI,EACjB,IAAM,EAAK,EAAK,IAAM,UAAU,MAC1B,EAAY,EAAkB,CAAE,EAEtC,GADI,IAAc,IAAA,KAAW,EAAS,KAAK,IAAI,EAAQ,CAAS,GAC5D,EAAI,IAAI,CAAE,EAAG,MAAU,UAAU,mCAAmC,EAAG,EAAE,EAC7E,EAAI,IAAI,CAAE,EACV,IAAM,EAAQ,EAAK,QAAQ,KAAK,CAAC,CAAC,OAClC,GAAI,EAAQ,EAAO,aACjB,MAAU,WAAW,sBAAsB,EAAG,gBAAgB,EAAO,aAAa,iBAAiB,EAGrG,GADA,GAAe,EACX,EAAc,EAAO,eACvB,MAAU,WAAW,iCAAiC,EAAO,eAAe,iBAAiB,EAE/F,OAAO,OAAO,OAAO,CACnB,GAAI,EAAK,KAAO,IAAA,GAAY,CAAC,EAAI,CAAE,GAAI,EAAK,EAAG,EAC/C,KAAM,EAAK,KACX,QAAS,EAAK,OAChB,CAAC,CACH,CAAC,CAAC,EACF,GAAI,EAAK,OAAS,EAAO,SACvB,MAAU,WAAW,iCAAiC,EAAO,SAAS,YAAY,EAEpF,OAAO,OAAO,OAAO,CACnB,qBAAsB,GAAO,sBAAwB,GACrD,mBACA,GAAG,EACH,MACF,CAAC,CACH,CAEA,SAAS,EAAa,EAA8B,CAClD,GAAI,EAAM,KAAO,IAAA,KAAc,OAAO,EAAM,IAAO,UAC9C,EAAM,GAAG,KAAK,CAAC,CAAC,SAAW,GAAK,EAAM,GAAG,OAAS,KAAO,KAAK,KAAK,EAAM,EAAE,GAC9E,MAAU,UAAU,sFAAsF,EAE5G,GAAI,CAAC,OAAO,OAAO,EAAU,EAAM,IAAI,EAAG,MAAU,UAAU,kCAAkC,OAAO,EAAM,IAAI,EAAE,EAAE,EACrH,GAAI,OAAO,EAAM,SAAY,UAAY,EAAM,QAAQ,KAAK,CAAC,CAAC,SAAW,EACvE,MAAU,UAAU,iDAAiD,CAEzE,CAEA,SAAS,EACP,EACyE,CACzE,IAAM,EAAW,EAAgB,EAAM,UAAY,KAAO,UAAU,EAC9D,EAAe,EAAgB,EAAM,cAAgB,MAAQ,cAAc,EAC3E,EAAiB,EAAgB,EAAM,gBAAkB,QAAa,gBAAgB,EAC5F,GAAI,EAAe,EACjB,MAAU,WAAW,0DAA0D,EAEjF,OAAO,OAAO,OAAO,CAAE,WAAU,eAAc,gBAAe,CAAC,CACjE,CAEA,SAAS,EAAgB,EAAe,EAAsB,CAC5D,GAAI,CAAC,OAAO,cAAc,CAAK,GAAK,EAAQ,EAC1C,MAAU,WAAW,gBAAgB,EAAK,iCAAiC,EAE7E,OAAO,CACT,CAEA,SAAS,EAAa,EAA6B,CAEjD,GADA,EAAa,CAAI,EACb,CAAC,EAAe,EAAK,SAAS,GAAK,CAAC,EAAe,EAAK,SAAS,EACnE,MAAU,UAAU,0DAA0D,CAElF,CAEA,SAAS,EAAe,EAAiC,CACvD,GAAI,OAAO,GAAU,UAAY,EAAM,SAAW,GAAK,EAAM,OAAS,GAAI,MAAO,GACjF,IAAM,EAAS,KAAK,MAAM,CAAK,EAC/B,GAAI,CAAC,OAAO,SAAS,CAAM,EAAG,MAAO,GACrC,GAAI,CAAE,OAAO,IAAI,KAAK,CAAM,CAAC,CAAC,YAAY,IAAM,CAAM,MAAQ,CAAE,MAAO,EAAM,CAC/E,CAEA,SAAS,EAAkB,EAAgC,CACzD,IAAM,EAAS,iBAAiB,KAAK,CAAE,CAAC,GAAG,GAC3C,GAAI,IAAW,IAAA,GAAW,OAC1B,IAAM,EAAU,OAAO,CAAM,EAC7B,OAAO,OAAO,cAAc,CAAO,GAAK,GAAW,GAAK,UACpD,EAAU,EACV,IAAA,EACN,CAEA,SAAS,EAAkB,EAAsB,EAA0B,CACzE,IACI,EAAO,GACP,EAAY,GAChB,IAAK,IAAM,KAAS,EAAQ,QAAS,CACnC,GAAI,EAAM,OAAS,OAAQ,SAC3B,IAAM,EAAY,EAAK,SAAW,EAAI,GAAK;EACrC,EAAY,EAAW,EAAK,OAClC,GAAI,EAAU,OAAS,EAAM,KAAK,QAAU,EAAW,CACrD,GAAQ,EAAY,EAAM,KAC1B,QACF,CACA,IAAM,EAAY,KAAK,IAAI,EAAG,EAAY,EAAU,OAAS,EAAa,EAC1E,GAAQ,EAAY,EAAM,KAAK,MAAM,EAAG,CAAS,EAAI,yBAAO,MAAM,EAAG,KAAK,IAAI,EAAG,EAAY,EAAU,OAAS,CAAS,CAAC,EAC1H,EAAY,GACZ,KACF,CACA,OAAO,EAAY,EAAK,MAAM,EAAG,CAAQ,EAAI,CAC/C,CAEA,SAAS,EAAe,EAAe,EAA0B,CAC/D,GAAI,EAAM,QAAU,EAAU,OAAO,EACrC,GAAI,GAAY,EAAG,OAAO,EAAM,MAAM,EAAG,CAAQ,EACjD,IACM,EAAO,KAAK,MAAM,EAAW,GAAiB,CAAC,EAC/C,EAAO,KAAK,OAAO,EAAW,GAAiB,CAAC,EACtD,OAAO,EAAM,MAAM,EAAG,CAAI,EAAI,IAAS,EAAM,MAAM,EAAM,OAAS,CAAI,CACxE"}

package/dist/agent/memory/persistence-types.d.ts

@@ -0,0 +1,44 @@
+import { SdkLogger } from "../../logging/types.js";
+import { AgentMemorySnapshot } from "./memory.js";
+//#region src/agent/memory/persistence-types.d.ts
+interface MemoryStoreOptions {
+  readonly signal: AbortSignal;
+  readonly logger: SdkLogger;
+}
+interface MemoryLoadResult {
+  readonly snapshot: AgentMemorySnapshot;
+  readonly revision: string;
+}
+interface MemoryCommitInput {
+  readonly key: string;
+  readonly snapshot: AgentMemorySnapshot;
+  readonly expectedRevision: string | null;
+}
+interface MemoryCommitResult {
+  readonly revision: string;
+}
+interface MemoryStore {
+  readonly kind: 'memory-store';
+  readonly apiVersion: 1;
+  readonly id: string;
+  readonly load: (key: string, options: MemoryStoreOptions) => Promise<MemoryLoadResult | undefined>;
+  readonly commit: (input: MemoryCommitInput, options: MemoryStoreOptions) => Promise<MemoryCommitResult>;
+}
+type MemoryStoreDefinition = Omit<MemoryStore, 'kind' | 'apiVersion'>;
+type MemoryScope = {
+  readonly kind: 'conversation';
+  readonly namespace: string;
+} | {
+  readonly kind: 'fixed';
+  readonly key: string;
+  readonly sharedAcrossSessions: true;
+};
+interface MemoryBinding {
+  readonly store: MemoryStore;
+  readonly bindingId: string;
+  readonly scope: MemoryScope;
+  readonly requirement: 'required' | 'best-effort';
+}
+//#endregion
+export { MemoryBinding, MemoryCommitInput, MemoryCommitResult, MemoryLoadResult, MemoryScope, MemoryStore, MemoryStoreDefinition, MemoryStoreOptions };
+//# sourceMappingURL=persistence-types.d.ts.map

package/dist/agent/memory/persistence-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-types.d.ts","names":[],"sources":["../../../src/agent/memory/persistence-types.ts"],"mappings":";;;UAGiB;WACN,QAAQ;WACR,QAAQ;;UAGF;WACN,UAAU;WACV;;UAGM;WACN;WACA,UAAU;WACV;;UAGM;WAA8B;;UAE9B;WACN;WACA;WACA;WACA,OAAO,aAAa,SAAS,uBAAuB,QAAQ;WAC5D,SAAS,OAAO,mBAAmB,SAAS,uBAAuB,QAAQ;;KAG1E,wBAAwB,KAAK;KAE7B;WACG;WAA+B;;WAC/B;WAAwB;WAAsB;;UAE5C;WACN,OAAO;WACP;WACA,OAAO;WACP"}

package/dist/agent/memory/surface-compaction.d.ts

@@ -0,0 +1,6 @@
+import { HistorySurfaceNode } from "../history/project.js";
+//#region src/agent/memory/surface-compaction.d.ts
+declare function selectCompactablePrefix(surface: readonly HistorySurfaceNode[], retainTokens: number): readonly HistorySurfaceNode[];
+//#endregion
+export { selectCompactablePrefix };
+//# sourceMappingURL=surface-compaction.d.ts.map

package/dist/agent/memory/surface-compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-compaction.d.ts","names":[],"sources":["../../../src/agent/memory/surface-compaction.ts"],"mappings":";;iBASgB,wBACd,kBAAkB,sBAClB,gCACU"}

package/dist/agent/memory/surface-compaction.js

@@ -0,0 +1,4 @@
+import{createMessage as e}from"../../message/message.js";import{estimateMessageTokens as t}from"./token-estimator.js";function n(e,n){if(e.length<2)return[];let r=0,a=e.length;for(let i=e.length-1;i>=0&&(r+=t(e[i]?.message),a=i,!(r>=n));i--);for(a=Math.max(1,Math.min(a,e.length-1));a>0&&!i(e.map(e=>e.message),a);)a--;return Object.freeze(e.slice(0,a))}function r(t,n,r){let i=0;for(let o of n){if(o.message.source.kind!==`tool`)continue;let n=o.message.content.flatMap(e=>e.type===`tool-result`?e.content.filter(e=>e.type===`text`):[]),s=n.reduce((e,t)=>e+[...t.text].length,0);if(s<=r)continue;let c=t.entries().find(e=>e.seq===o.seq);if(c?.event.kind!==`tool-result`)continue;let l=Math.max(1,Math.floor(r/Math.max(1,n.length))),u=o.message.content.map(e=>e.type===`tool-result`?{...e,content:e.content.map(e=>e.type===`text`?{...e,text:a(e.text,l)}:e)}:e),d=e({role:`user`,source:o.message.source,content:u}),f=u.flatMap(e=>e.type===`tool-result`?e.content.filter(e=>e.type===`text`):[]).reduce((e,t)=>e+[...t.text].length,0);t.appendBatch([{event:{kind:`compaction-prune`,callId:c.event.callId,originalSeq:o.seq,charsBefore:s,charsAfter:f}},{event:{...c.event,message:d},surfaceOp:{op:`replace`,from:o.seq,to:o.seq,targets:[o.seq]}}]),i++}return i}function i(e,t){let n=new Map;for(let r=0;r<e.length;r++){let i=r<t?`head`:`tail`;for(let t of e[r]?.content??[])t.type===`tool-call`&&n.set(t.id,i)}for(let r=0;r<e.length;r++){let i=r<t?`head`:`tail`;for(let t of e[r]?.content??[])if(t.type===`tool-result`&&n.get(t.toolCallId)!==i)return!1}return!0}function a(e,t){let n=[...e];if(n.length<=t)return e;let r=[...`
+…[tool result pruned for context]…
+`];if(t<=r.length)return n.slice(0,t).join(``);let i=Math.ceil((t-r.length)/2),a=Math.floor((t-r.length)/2);return[...n.slice(0,i),...r,...n.slice(n.length-a)].join(``)}export{r as pruneToolResults,n as selectCompactablePrefix};
+//# sourceMappingURL=surface-compaction.js.map

package/dist/agent/memory/surface-compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-compaction.js","names":[],"sources":["../../../src/agent/memory/surface-compaction.ts"],"sourcesContent":["/** Surface range selection and lossless-log tool-result pruning. */\n\nimport type { ContentBlock } from '../../message/index.ts'\nimport { createMessage, type Message } from '../../message/index.ts'\nimport type { ToolCallId } from '../../primitives/index.ts'\nimport type { History } from '../history/history.ts'\nimport type { HistorySurfaceNode } from '../history/project.ts'\nimport { estimateMessageTokens } from './token-estimator.ts'\n\nexport function selectCompactablePrefix(\n  surface: readonly HistorySurfaceNode[],\n  retainTokens: number,\n): readonly HistorySurfaceNode[] {\n  if (surface.length < 2) return []\n  let accumulated = 0\n  let keepFrom = surface.length\n  for (let index = surface.length - 1; index >= 0; index--) {\n    accumulated += estimateMessageTokens(surface[index]?.message)\n    keepFrom = index\n    if (accumulated >= retainTokens) break\n  }\n  keepFrom = Math.max(1, Math.min(keepFrom, surface.length - 1))\n  while (keepFrom > 0 && !toolPairingBalanced(surface.map(node => node.message), keepFrom)) keepFrom--\n  return Object.freeze(surface.slice(0, keepFrom))\n}\n\n/** Replace oversized model-visible tool text while retaining the full original log entry. */\nexport function pruneToolResults(\n  history: History,\n  surface: readonly HistorySurfaceNode[],\n  maxChars: number,\n): number {\n  let pruned = 0\n  for (const node of surface) {\n    if (node.message.source.kind !== 'tool') continue\n    const textBlocks = node.message.content.flatMap(block =>\n      block.type === 'tool-result'\n        ? block.content.filter((child): child is Extract<ContentBlock, { type: 'text' }> => child.type === 'text')\n        : [])\n    const charsBefore = textBlocks.reduce((total, block) => total + [...block.text].length, 0)\n    if (charsBefore <= maxChars) continue\n    const sourceEntry = history.entries().find(entry => entry.seq === node.seq)\n    if (sourceEntry?.event.kind !== 'tool-result') continue\n    const perBlock = Math.max(1, Math.floor(maxChars / Math.max(1, textBlocks.length)))\n    const content = node.message.content.map(block => block.type !== 'tool-result'\n      ? block\n      : {\n        ...block,\n        content: block.content.map(child => child.type === 'text'\n          ? { ...child, text: truncateMiddleCodePoints(child.text, perBlock) }\n          : child),\n      })\n    const replacement = createMessage({ role: 'user', source: node.message.source, content })\n    const charsAfter = content.flatMap(block => block.type === 'tool-result'\n      ? block.content.filter((child): child is Extract<ContentBlock, { type: 'text' }> => child.type === 'text')\n      : []).reduce((total, block) => total + [...block.text].length, 0)\n    history.appendBatch([\n      { event: {\n        kind: 'compaction-prune', callId: sourceEntry.event.callId,\n        originalSeq: node.seq, charsBefore, charsAfter,\n      } },\n      {\n        event: { ...sourceEntry.event, message: replacement },\n        surfaceOp: { op: 'replace', from: node.seq, to: node.seq, targets: [node.seq] },\n      },\n    ])\n    pruned++\n  }\n  return pruned\n}\n\nfunction toolPairingBalanced(messages: readonly Message[], split: number): boolean {\n  const side = new Map<ToolCallId, 'head' | 'tail'>()\n  for (let index = 0; index < messages.length; index++) {\n    const location = index < split ? 'head' : 'tail'\n    for (const block of messages[index]?.content ?? []) {\n      if (block.type === 'tool-call') side.set(block.id, location)\n    }\n  }\n  for (let index = 0; index < messages.length; index++) {\n    const location = index < split ? 'head' : 'tail'\n    for (const block of messages[index]?.content ?? []) {\n      if (block.type === 'tool-result' && side.get(block.toolCallId) !== location) return false\n    }\n  }\n  return true\n}\n\nfunction truncateMiddleCodePoints(value: string, maxChars: number): string {\n  const points = [...value]\n  if (points.length <= maxChars) return value\n  const marker = [...'\\n…[tool result pruned for context]…\\n']\n  if (maxChars <= marker.length) return points.slice(0, maxChars).join('')\n  const head = Math.ceil((maxChars - marker.length) / 2)\n  const tail = Math.floor((maxChars - marker.length) / 2)\n  return [...points.slice(0, head), ...marker, ...points.slice(points.length - tail)].join('')\n}\n"],"mappings":"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"}

package/dist/agent/memory/token-estimator.d.ts

@@ -0,0 +1,12 @@
+import { Message } from "../../message/message.js";
+import { ModelToolSchema } from "../../contract/tool.js";
+//#region src/agent/memory/token-estimator.d.ts
+declare function estimateContextTokens(input: {
+  readonly system?: string;
+  readonly messages: readonly Message[];
+  readonly tools?: readonly ModelToolSchema[];
+}): number;
+declare function estimateMessageTokens(message: Message | undefined): number;
+//#endregion
+export { estimateContextTokens, estimateMessageTokens };
+//# sourceMappingURL=token-estimator.d.ts.map

package/dist/agent/memory/token-estimator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimator.d.ts","names":[],"sources":["../../../src/agent/memory/token-estimator.ts"],"mappings":";;;iBAMgB,sBAAsB;WAC3B;WACA,mBAAmB;WACnB,iBAAiB;;iBAQZ,sBAAsB,SAAS"}

package/dist/agent/memory/token-estimator.js

@@ -0,0 +1,2 @@
+function e(e){let n=e.system===void 0?0:r(e.system),a=e.messages.reduce((e,n)=>e+t(n),0),o=e.tools?.reduce((e,t)=>e+r(i(t))+8,0)??0;return n+a+o+8}function t(e){return e===void 0?0:4+e.content.reduce((e,t)=>e+n(t),0)}function n(e){switch(e.type){case`text`:return r(e.text)+2;case`reasoning`:return r(e.text)+r(i(e.providerState))+2;case`image`:return e.source.kind===`base64`?Math.max(1024,r(e.source.data)):512;case`tool-call`:return r(e.name)+r(e.arguments)+8;case`tool-result`:return e.content.reduce((e,t)=>e+n(t),8);case`native-tool-call`:return r(i(e))+8;default:return r(i(e))+4}}function r(e){return Math.ceil(e.length/4)}function i(e){try{return JSON.stringify(e)??``}catch{return String(e)}}export{e as estimateContextTokens,t as estimateMessageTokens};
+//# sourceMappingURL=token-estimator.js.map

package/dist/agent/memory/token-estimator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-estimator.js","names":[],"sources":["../../../src/agent/memory/token-estimator.ts"],"sourcesContent":["/** Provider-neutral deterministic context estimator used by compaction policy. */\n\nimport type { ModelToolSchema } from '../../contract/index.ts'\nimport type { ContentBlock } from '../../message/index.ts'\nimport type { Message } from '../../message/index.ts'\n\nexport function estimateContextTokens(input: {\n  readonly system?: string\n  readonly messages: readonly Message[]\n  readonly tools?: readonly ModelToolSchema[]\n}): number {\n  const system = input.system === undefined ? 0 : estimateTextTokens(input.system)\n  const messages = input.messages.reduce((total, message) => total + estimateMessageTokens(message), 0)\n  const tools = input.tools?.reduce((total, tool) => total + estimateTextTokens(safeJson(tool)) + 8, 0) ?? 0\n  return system + messages + tools + 8\n}\n\nexport function estimateMessageTokens(message: Message | undefined): number {\n  if (message === undefined) return 0\n  return 4 + message.content.reduce((total, block) => total + estimateBlockTokens(block), 0)\n}\n\nfunction estimateBlockTokens(block: ContentBlock): number {\n  switch (block.type) {\n    case 'text': return estimateTextTokens(block.text) + 2\n    case 'reasoning': return estimateTextTokens(block.text) + estimateTextTokens(safeJson(block.providerState)) + 2\n    case 'image': return block.source.kind === 'base64'\n      ? Math.max(1024, estimateTextTokens(block.source.data))\n      : 512\n    case 'tool-call': return estimateTextTokens(block.name) + estimateTextTokens(block.arguments) + 8\n    case 'tool-result': return block.content.reduce((total, child) => total + estimateBlockTokens(child), 8)\n    case 'native-tool-call': return estimateTextTokens(safeJson(block)) + 8\n    default: return estimateTextTokens(safeJson(block)) + 4\n  }\n}\n\nfunction estimateTextTokens(text: string): number { return Math.ceil(text.length / 4) }\nfunction safeJson(value: unknown): string {\n  try { return JSON.stringify(value) ?? '' } catch { return String(value) }\n}\n"],"mappings":"AAMA,SAAgB,EAAsB,EAI3B,CACT,IAAM,EAAS,EAAM,SAAW,IAAA,GAAY,EAAI,EAAmB,EAAM,MAAM,EACzE,EAAW,EAAM,SAAS,QAAQ,EAAO,IAAY,EAAQ,EAAsB,CAAO,EAAG,CAAC,EAC9F,EAAQ,EAAM,OAAO,QAAQ,EAAO,IAAS,EAAQ,EAAmB,EAAS,CAAI,CAAC,EAAI,EAAG,CAAC,GAAK,EACzG,OAAO,EAAS,EAAW,EAAQ,CACrC,CAEA,SAAgB,EAAsB,EAAsC,CAE1E,OADI,IAAY,IAAA,GAAkB,EAC3B,EAAI,EAAQ,QAAQ,QAAQ,EAAO,IAAU,EAAQ,EAAoB,CAAK,EAAG,CAAC,CAC3F,CAEA,SAAS,EAAoB,EAA6B,CACxD,OAAQ,EAAM,KAAd,CACE,IAAK,OAAQ,OAAO,EAAmB,EAAM,IAAI,EAAI,EACrD,IAAK,YAAa,OAAO,EAAmB,EAAM,IAAI,EAAI,EAAmB,EAAS,EAAM,aAAa,CAAC,EAAI,EAC9G,IAAK,QAAS,OAAO,EAAM,OAAO,OAAS,SACvC,KAAK,IAAI,KAAM,EAAmB,EAAM,OAAO,IAAI,CAAC,EACpD,IACJ,IAAK,YAAa,OAAO,EAAmB,EAAM,IAAI,EAAI,EAAmB,EAAM,SAAS,EAAI,EAChG,IAAK,cAAe,OAAO,EAAM,QAAQ,QAAQ,EAAO,IAAU,EAAQ,EAAoB,CAAK,EAAG,CAAC,EACvG,IAAK,mBAAoB,OAAO,EAAmB,EAAS,CAAK,CAAC,EAAI,EACtE,QAAS,OAAO,EAAmB,EAAS,CAAK,CAAC,EAAI,CACxD,CACF,CAEA,SAAS,EAAmB,EAAsB,CAAE,OAAO,KAAK,KAAK,EAAK,OAAS,CAAC,CAAE,CACtF,SAAS,EAAS,EAAwB,CACxC,GAAI,CAAE,OAAO,KAAK,UAAU,CAAK,GAAK,EAAG,MAAQ,CAAE,OAAO,OAAO,CAAK,CAAE,CAC1E"}

package/dist/agent/mode/run-agent.d.ts

@@ -0,0 +1,79 @@
+import { CallConfig } from "../../contract/call-config.js";
+import { ToolCatalog } from "../tool/registry.js";
+import { AgentEvent, TurnHooks, TurnOutcome } from "../loop/events.js";
+import { TurnBounds } from "../loop/types.js";
+import { RunTurnOptions } from "../loop/turn/types.js";
+import { UserInputBroker, UserInputRequest, UserInputResponse } from "./user-input.js";
+//#region src/agent/mode/run-agent.d.ts
+declare const AGENT_CONTROL_TOOLS: Readonly<{
+  readonly complete: 'submit_result';
+  readonly requestUserInput: 'request_user_input';
+}>;
+/** Default high-level runtime requested by this SDK; `runTurn` remains provider-neutral. */
+type AgentMode = 'basic' | 'deep' | 'deep-human-in-loop';
+interface AgentRunCommon extends Omit<RunTurnOptions, 'bounds' | 'commentary' | 'config' | 'hooks' | 'system' | 'tools'> {
+  /** Explicit low-level model binding; composition users can select a configured provider default instead. */
+  readonly config: CallConfig;
+  readonly tools?: ToolCatalog;
+  readonly system?: string;
+  /** Maximum normal model iterations. A forced final answer may use one extra request. */
+  /** Model steps per prompt; 'auto' keeps completion and resource guards only. */
+  readonly maxTurns?: number | 'auto';
+  readonly bounds?: Omit<Partial<TurnBounds>, 'maxSteps'>;
+  readonly commentary?: RunTurnOptions['commentary'];
+  readonly hooks?: TurnHooks;
+}
+interface BasicAgentOptions extends AgentRunCommon {
+  readonly mode?: 'basic';
+}
+interface DeepAgentOptions extends AgentRunCommon {
+  readonly mode: 'deep';
+  /** Optional in deep mode: expose a blocking clarification tool when configured. */
+  readonly userInput?: UserInputBroker;
+}
+interface HumanInLoopAgentOptions extends AgentRunCommon {
+  readonly mode: 'deep-human-in-loop';
+  /** Required in HIL mode: the tool call remains parked until this broker answers. */
+  readonly userInput: UserInputBroker;
+}
+type RunAgentOptions = BasicAgentOptions | DeepAgentOptions | HumanInLoopAgentOptions;
+interface CompletionSubmission {
+  readonly summary: string;
+  readonly evidence: readonly string[];
+}
+interface AgentRunOutcome extends TurnOutcome {
+  readonly mode: AgentMode;
+  /** Deep modes are complete only after the model explicitly submits its self-check. */
+  readonly completed: boolean;
+  readonly completion?: CompletionSubmission;
+}
+interface AgentModeStartEvent {
+  readonly type: 'agent-start';
+  readonly mode: AgentMode;
+  readonly maxTurns: number | 'auto';
+}
+interface UserInputRequestEvent {
+  readonly type: 'user-input-request';
+  readonly request: UserInputRequest;
+}
+interface UserInputResponseEvent {
+  readonly type: 'user-input-response';
+  readonly request: UserInputRequest;
+  readonly response: UserInputResponse | 'abort';
+}
+interface AgentModeEndEvent {
+  readonly type: 'agent-end';
+  readonly outcome: AgentRunOutcome;
+}
+type AgentRunEvent = AgentEvent | AgentModeStartEvent | UserInputRequestEvent | UserInputResponseEvent | AgentModeEndEvent;
+/**
+ * Run an agent in basic, self-checking deep, or deep human-in-loop mode.
+ *
+ * The low-level `turn-*`, trace, commentary, reasoning-summary, and tool events are
+ * forwarded unchanged. High-level `agent-*` and `user-input-*` events make GUI
+ * orchestration possible without parsing assistant prose.
+ */
+declare function runAgent(options: RunAgentOptions): AsyncIterable<AgentRunEvent>;
+//#endregion
+export { AGENT_CONTROL_TOOLS, AgentMode, AgentRunEvent, AgentRunOutcome, BasicAgentOptions, CompletionSubmission, DeepAgentOptions, HumanInLoopAgentOptions, RunAgentOptions, runAgent };
+//# sourceMappingURL=run-agent.d.ts.map

package/dist/agent/mode/run-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-agent.d.ts","names":[],"sources":["../../../src/agent/mode/run-agent.ts"],"mappings":";;;;;;;cAkBa,qBAAmB;WACpB;WACQ;;;KAIR;UAEF,uBAAuB,KAAK;;WAE3B,QAAQ;WACR,QAAQ;WACR;;;WAGA;WACA,SAAS,KAAK,QAAQ;WACtB,aAAa;WACb,QAAQ;;UAGF,0BAA0B;WAChC;;UAGM,yBAAyB;WAC/B;;WAEA,YAAY;;UAGN,gCAAgC;WACtC;;WAEA,WAAW;;KAGV,kBAAkB,oBAAoB,mBAAmB;UAEpD;WACN;WACA;;UAGM,wBAAwB;WAC9B,MAAM;;WAEN;WACA,aAAa;;UAGd;WACC;WACA,MAAM;WACN;;UAED;WACC;WACA,SAAS;;UAEV;WACC;WACA,SAAS;WACT,UAAU;;UAEX;WACC;WACA,SAAS;;KAGR,gBAAgB,aACxB,sBACA,wBACA,yBACA;;;;;;;;iBAsBY,SAAS,SAAS,kBAAkB,cAAc"}

package/dist/agent/mode/run-agent.js

@@ -0,0 +1,4 @@
+import{detachedFrozen as e}from"../../primitives/snapshot.js";import{waitForSettlement as t}from"../../async/settlement.js";import{createUserMessage as n}from"../../message/message.js";import{defineTool as r}from"../tool/definition.js";import{AwaitedEventQueue as i}from"../loop/queue.js";import{readSpillTool as a}from"../tool/output-budget.js";import{runTurn as o}from"../loop/run-turn.js";const s=Object.freeze({complete:`submit_result`,requestUserInput:`request_user_input`});function c(n){return{async*[Symbol.asyncIterator](){let r=new i,a=new AbortController,o=T(n.teardownTimeoutMs??3e4,`teardownTimeoutMs`),s=n.signal===void 0?a.signal:AbortSignal.any([n.signal,a.signal]),c=Promise.resolve(),u=l(n,s,t=>{let n=c.then(()=>r.push(e(t)));return c=n.catch(()=>void 0),n}).then(async()=>{await c,r.close()},async e=>{await c,r.fail(e)});try{for(;;){let e=await r.take();if(e.done)break;yield e.value}await u}finally{if(a.abort(Error(`agent event consumer stopped`)),r.close(),!await t(u,o)){let e=Error(`agent producer ignored cancellation for more than ${o}ms`,{cause:a.signal.reason});throw e.code=`AGENT_TEARDOWN_TIMEOUT`,e}}}}}async function l(e,t,n){let r=e.mode??`basic`;if(![`basic`,`deep`,`deep-human-in-loop`].includes(r))throw RangeError(`unsupported agent mode "${String(r)}"`);let i=`userInput`in e?e.userInput:void 0;if(r===`deep-human-in-loop`&&(i===void 0||typeof i.request!=`function`))throw TypeError(`deep-human-in-loop mode requires a UserInputBroker`);let c=e.maxTurns??16;if(c!==`auto`&&(!Number.isSafeInteger(c)||c<1))throw RangeError(`maxTurns must be a positive safe integer or 'auto'`);await n({type:`agent-start`,mode:r,maxTurns:c});let l={completion:void 0,userAborted:!1,unverifiedAnswers:0,completionInvalidated:!1},p=r!==`basic`,_=e.mode===`deep`||e.mode===`deep-human-in-loop`?i:void 0,v=[];e.spillStore!==void 0&&v.push(a(e.spillStore)),p&&v.push(u()),_!==void 0&&r!==`basic`&&v.push(d(r,_,l,n,e.accounting));let y=v.length===0?e.tools:m(e.tools,v),b=p?f(e.hooks,e.history,l,c):e.hooks,C={registry:e.registry,config:e.config,history:e.history,...y===void 0?{}:{tools:y},...e.nativeTools===void 0?{}:{nativeTools:e.nativeTools},...e.toolChoice===void 0?{}:{toolChoice:e.toolChoice},...e.imagePolicy===void 0?{}:{imagePolicy:e.imagePolicy},...e.validateOutput===void 0?{}:{validateOutput:e.validateOutput},...e.outputFormat===void 0?{}:{outputFormat:e.outputFormat},system:S(e.system,x(r,_!==void 0)),...e.interceptors===void 0?{}:{interceptors:h(e.interceptors)},...e.approvals===void 0?{}:{approvals:e.approvals},bounds:{...e.bounds,maxSteps:c},...b===void 0?{}:{hooks:b},signal:t,...e.logger===void 0?{}:{logger:e.logger},commentary:e.commentary??`concise`,teardownTimeoutMs:e.teardownTimeoutMs??3e4,...e.modelTimeoutMs===void 0?{}:{modelTimeoutMs:e.modelTimeoutMs},...e.maxModelRequestBytes===void 0?{}:{maxModelRequestBytes:e.maxModelRequestBytes},...e.maxModelResponseBytes===void 0?{}:{maxModelResponseBytes:e.maxModelResponseBytes},...e.maxModelStreamEvents===void 0?{}:{maxModelStreamEvents:e.maxModelStreamEvents},...e.hookTimeoutMs===void 0?{}:{hookTimeoutMs:e.hookTimeoutMs},...e.hookTeardownTimeoutMs===void 0?{}:{hookTeardownTimeoutMs:e.hookTeardownTimeoutMs},...e.trace===void 0?{}:{trace:e.trace},...e.accounting===void 0?{}:{accounting:e.accounting},...e.spillStore===void 0?{}:{spillStore:e.spillStore},...e.contextSections===void 0?{}:{contextSections:e.contextSections}},w,T=[],E;for await(let e of o(C))e.type===`step-start`?(T=[],E=void 0):e.type===`tool-call`?(T.push(e.call.toolName),e.call.toolName!==s.complete&&y?.get(e.call.toolName)?.completionExempt!==!0&&(l.completion!==void 0&&(l.completionInvalidated=!0),l.completion=void 0,l.unverifiedAnswers=0)):e.type===`tool-result`&&e.call.toolName===s.complete&&!e.result.isError?E=g(e.result.value):e.type===`step-end`&&E!==void 0&&T.filter(e=>e===s.complete).length===1&&T.every(e=>e===s.complete||y?.get(e)?.completionExempt===!0)&&(l.completion=E,l.completionInvalidated=!1),e.type===`turn-end`&&(w=e.outcome),await n(e);if(w===void 0)throw Error(`runTurn ended without a turn-end event`);let D=r===`basic`?w.reason.kind===`completed`||w.reason.kind===`concluded-by-tool`:l.completion!==void 0&&!l.userAborted&&(w.reason.kind===`completed`||w.reason.kind===`concluded-by-tool`||w.reason.kind===`budget-exhausted`&&w.reason.forcedFinalAnswer)&&w.text.trim()!==``;await n({type:`agent-end`,outcome:{...w,mode:r,completed:D,...l.completion===void 0?{}:{completion:l.completion}}})}function u(){return r({name:s.complete,description:`Submit the self-check only when the user objective and constraints are fully satisfied. After acceptance, give the user the final answer.`,budgetExempt:!0,parameters:{type:`object`,properties:{summary:{type:`string`,description:`Concise statement of what was completed.`},evidence:{type:`array`,items:{type:`string`},description:`Concrete checks or tool results showing the objective is satisfied.`}},required:[`summary`,`evidence`],additionalProperties:!1},parse:v,execute:e=>({accepted:!0,summary:e.summary,evidence:[...e.evidence],instruction:`This self-check is accepted for the current run. Now provide the substantive final report itself: findings or changes, evidence or sources, checks performed, and remaining limitations. Do not merely say the self-check passed or refer to an earlier message. Do not call submit_result again in this run unless you perform new substantive tool work that invalidates this submission. A later user request or worker follow-up starts a new run and needs its own self-check.`})})}function d(e,t,n,i,a){return r({name:s.requestUserInput,budgetExempt:!0,description:e===`deep-human-in-loop`?`Ask the user one to three short questions when a material choice or missing fact requires human input, then wait for the response. Provide 2-3 mutually exclusive suggestions; free-form input is added by the client.`:`Ask the user one to three short clarification questions only when blocked, then wait for the response. Provide suggested choices; free-form input is added by the client.`,parameters:b(),parse:y,execute:async({questions:e},r)=>{let o=a?.startOperation(`user-input`,{toolCallId:r.callId,data:{questionCount:e.length}}),s={requestId:r.callId,callId:r.callId,turn:r.turn,step:r.step,questions:e,isBlocking:!0};try{let c=t.request(s,r.signal);await i({type:`user-input-request`,request:s});let l=await c;return await i({type:`user-input-response`,request:s,response:l}),l===`abort`?(n.userAborted=!0,r.concludeTurn(),o!==void 0&&a?.endOperation(o,`aborted`),{aborted:!0}):(o!==void 0&&a?.endOperation(o,`success`),_(l,e))}catch(e){throw o!==void 0&&a?.endOperation(o,r.signal.aborted?`aborted`:`error`,{error:e}),e}}})}function f(e,t,r,i){return{...e,onTurnEnd:async a=>{await e?.onTurnEnd?.(a),!(a.outcome.reason.kind!==`completed`||i!==`auto`&&a.outcome.steps>=i||r.completion!==void 0||r.userAborted)&&(r.unverifiedAnswers++,!(r.unverifiedAnswers>=3)&&t.append({kind:`user`,message:n({source:{kind:`app`,producer:`deep-mode-self-check`},content:[{type:`text`,text:(r.completionInvalidated?`Your previously accepted submission is no longer current because you called another substantive tool afterwards. Review the later tool results and call ${s.complete} again when complete; the old instruction not to resubmit no longer applies. `:``)+`Self-check required: this run has no accepted current self-check. Acceptance recorded in an earlier run does not complete this request or follow-up; an earlier instruction not to resubmit applied only to that earlier run. Compare the current result against the user's objective and every constraint. If anything is missing, continue with tools. If blocked and request_user_input is available, ask the user. Only when the work is actually complete, call ${s.complete}. Rephrasing a completion claim without submitting does not satisfy this gate.`}]})}))}}}var p=class{definitions;constructor(e,t){let n=new Map;for(let t of e?.names()??[]){let r=e?.get(t);r!==void 0&&n.set(t,r)}for(let e of t){if(n.has(e.name))throw Error(`tool name "${e.name}" is reserved by the selected agent mode`);n.set(e.name,e)}this.definitions=n}get(e){return this.definitions.get(e)}has(e){return this.definitions.has(e)}names(){return[...this.definitions.keys()]}schemas(){return[...this.definitions.values()].map(({name:e,description:t,parameters:n})=>({name:e,description:t,parameters:structuredClone(n)}))}executionMode(e,t){let n=this.definitions.get(e);if(n===void 0)return`exclusive`;try{return n.isConcurrencySafe?.(t)===!0?`parallel`:`exclusive`}catch{return`exclusive`}}};function m(e,t){return new p(e,t)}function h(e){let t=new Set(Object.values(s));return e.map(e=>({name:e.name,...e.before===void 0?{}:{before:(n,r)=>t.has(n.toolName)?r():e.before(n,r)},...e.around===void 0?{}:{around:(n,r)=>t.has(n.toolName)?r():e.around(n,r)},...e.after===void 0?{}:{after:(n,r,i)=>t.has(n.toolName)?i():e.after(n,r,i)}}))}function g(e){let t=C(e,`submit_result result`);return v({summary:t.summary,evidence:t.evidence})}function _(e,t){let n=new Set(t.map(e=>e.id));for(let t of n){let n=e.answers[t];if(n===void 0||!Array.isArray(n.answers)||n.answers.length===0||n.answers.some(e=>typeof e!=`string`||e.trim().length===0))throw Error(`the user-input broker returned no valid answer for "${t}"`)}for(let t of Object.keys(e.answers))if(!n.has(t))throw Error(`the user-input broker returned an answer for unknown question "${t}"`);return e}function v(e){let t=C(e,`submit_result arguments`);if(typeof t.summary!=`string`||t.summary.trim().length===0)throw Error(`summary must be a non-empty string`);if(!Array.isArray(t.evidence)||t.evidence.some(e=>typeof e!=`string`||e.trim().length===0))throw Error(`evidence must be an array of non-empty strings`);return{summary:t.summary,evidence:t.evidence}}function y(e){let t=C(e,`request_user_input arguments`);if(!Array.isArray(t.questions)||t.questions.length<1||t.questions.length>3)throw Error(`questions must contain one to three items`);let n=new Set,r=t.questions.map((e,t)=>{let r=C(e,`questions[${t}]`),i=w(r.id,`questions[${t}].id`);if(!/^[a-z][a-z0-9_]*$/.test(i))throw Error(`questions[${t}].id must be snake_case`);if(n.has(i))throw Error(`question id "${i}" is duplicated`);n.add(i);let a=w(r.header,`questions[${t}].header`),o=w(r.question,`questions[${t}].question`);if(!Array.isArray(r.options)||r.options.length<2||r.options.length>3)throw Error(`questions[${t}].options must contain two or three choices`);let s=r.options.map((e,n)=>{let r=C(e,`questions[${t}].options[${n}]`);return{label:w(r.label,`questions[${t}].options[${n}].label`),description:w(r.description,`questions[${t}].options[${n}].description`)}});return Object.freeze({id:i,header:a,question:o,options:Object.freeze(s),allowFreeForm:!0})});return{questions:Object.freeze(r)}}function b(){return{type:`object`,properties:{questions:{type:`array`,minItems:1,maxItems:3,description:`Questions to show the user. Prefer one and do not exceed three.`,items:{type:`object`,additionalProperties:!1,properties:{id:{type:`string`,description:`Stable snake_case answer key.`},header:{type:`string`,description:`Short UI label, ideally 12 characters or fewer.`},question:{type:`string`,description:`Single-sentence question.`},options:{type:`array`,minItems:2,maxItems:3,description:`Mutually exclusive choices. Put the recommended choice first and suffix its label with "(Recommended)". Do not add Other; the client supplies free-form input.`,items:{type:`object`,additionalProperties:!1,properties:{label:{type:`string`,description:`User-facing label, one to five words.`},description:{type:`string`,description:`One sentence explaining impact or trade-off.`}},required:[`label`,`description`]}}},required:[`id`,`header`,`question`,`options`]}}},required:[`questions`],additionalProperties:!1}}function x(e,t){if(e===`basic`)return[`Work as a bounded tool-using agent. Use available tools proactively when they materially improve correctness.`,`Stay within the configured iteration budget, then give the best final answer supported by the gathered results.`].join(` `);let n=t?`If a missing fact or material user choice blocks correct progress, call ${s.requestUserInput} and continue after the answer.`:`If blocked by missing user input, state that limitation plainly in the final response.`,r=e===`deep-human-in-loop`?`For material choices, surface 2-3 concise options with the recommended option first; the UI also permits free-form feedback.`:``;return[`Work autonomously in deep mode. After every tool result, compare the evidence against the user objective and all constraints; continue until gaps are closed.`,`Do not treat a plausible draft as completion. When the work is actually complete, call ${s.complete} with a summary and concrete evidence, then provide the final answer.`,n,r,`Never reveal private chain-of-thought. Use concise user-visible commentary for intent, progress, observations, and decisions.`].filter(Boolean).join(` `)}function S(...e){return e.filter(e=>e!==void 0&&e.length>0).join(`
+
+`)}function C(e,t){if(typeof e!=`object`||!e||Array.isArray(e))throw Error(`${t} must be an object`);return e}function w(e,t){if(typeof e!=`string`||e.trim().length===0)throw Error(`${t} must be a non-empty string`);return e}function T(e,t){if(!Number.isFinite(e)||e<=0)throw RangeError(`${t} must be a positive finite number`);return e}export{s as AGENT_CONTROL_TOOLS,c as runAgent};
+//# sourceMappingURL=run-agent.js.map

package/dist/agent/mode/run-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-agent.js","names":[],"sources":["../../../src/agent/mode/run-agent.ts"],"sourcesContent":["/** High-level agent modes built on the provider-neutral bounded tool loop. */\n\nimport { createUserMessage } from '../../message/index.ts'\nimport type { CallConfig } from '../../contract/index.ts'\nimport type { JsonObject } from '../../primitives/index.ts'\nimport { detachedFrozen } from '../../primitives/index.ts'\nimport { runTurn, type RunTurnOptions } from '../loop/run-turn.ts'\nimport { AwaitedEventQueue } from '../loop/queue.ts'\nimport type { AgentEvent, TurnBounds, TurnHooks, TurnOutcome } from '../loop/types.ts'\nimport { defineTool, type ToolDefinition, type ToolExecutionMode } from '../tool/definition.ts'\nimport { readSpillTool } from '../tool/output-budget.ts'\nimport type { ToolInterceptor } from '../tool/pipeline.ts'\nimport type { ToolCatalog } from '../tool/registry.ts'\nimport { waitForSettlement } from '../../async/index.ts'\nimport type {\n  UserInputBroker, UserInputQuestion, UserInputRequest, UserInputResponse,\n} from './user-input.ts'\n\nexport const AGENT_CONTROL_TOOLS = Object.freeze({\n  complete: 'submit_result',\n  requestUserInput: 'request_user_input',\n} as const)\n\n/** Default high-level runtime requested by this SDK; `runTurn` remains provider-neutral. */\nexport type AgentMode = 'basic' | 'deep' | 'deep-human-in-loop'\n\ninterface AgentRunCommon extends Omit<RunTurnOptions, 'bounds' | 'commentary' | 'config' | 'hooks' | 'system' | 'tools'> {\n  /** Explicit low-level model binding; composition users can select a configured provider default instead. */\n  readonly config: CallConfig\n  readonly tools?: ToolCatalog\n  readonly system?: string\n  /** Maximum normal model iterations. A forced final answer may use one extra request. */\n  /** Model steps per prompt; 'auto' keeps completion and resource guards only. */\n  readonly maxTurns?: number | 'auto'\n  readonly bounds?: Omit<Partial<TurnBounds>, 'maxSteps'>\n  readonly commentary?: RunTurnOptions['commentary']\n  readonly hooks?: TurnHooks\n}\n\nexport interface BasicAgentOptions extends AgentRunCommon {\n  readonly mode?: 'basic'\n}\n\nexport interface DeepAgentOptions extends AgentRunCommon {\n  readonly mode: 'deep'\n  /** Optional in deep mode: expose a blocking clarification tool when configured. */\n  readonly userInput?: UserInputBroker\n}\n\nexport interface HumanInLoopAgentOptions extends AgentRunCommon {\n  readonly mode: 'deep-human-in-loop'\n  /** Required in HIL mode: the tool call remains parked until this broker answers. */\n  readonly userInput: UserInputBroker\n}\n\nexport type RunAgentOptions = BasicAgentOptions | DeepAgentOptions | HumanInLoopAgentOptions\n\nexport interface CompletionSubmission {\n  readonly summary: string\n  readonly evidence: readonly string[]\n}\n\nexport interface AgentRunOutcome extends TurnOutcome {\n  readonly mode: AgentMode\n  /** Deep modes are complete only after the model explicitly submits its self-check. */\n  readonly completed: boolean\n  readonly completion?: CompletionSubmission\n}\n\ninterface AgentModeStartEvent {\n  readonly type: 'agent-start'\n  readonly mode: AgentMode\n  readonly maxTurns: number | 'auto'\n}\ninterface UserInputRequestEvent {\n  readonly type: 'user-input-request'\n  readonly request: UserInputRequest\n}\ninterface UserInputResponseEvent {\n  readonly type: 'user-input-response'\n  readonly request: UserInputRequest\n  readonly response: UserInputResponse | 'abort'\n}\ninterface AgentModeEndEvent {\n  readonly type: 'agent-end'\n  readonly outcome: AgentRunOutcome\n}\n\nexport type AgentRunEvent = AgentEvent\n  | AgentModeStartEvent\n  | UserInputRequestEvent\n  | UserInputResponseEvent\n  | AgentModeEndEvent\n\ninterface DeepState {\n  completion: CompletionSubmission | undefined\n  userAborted: boolean\n  /** Answers without intervening substantive tool work or an accepted check. */\n  unverifiedAnswers: number\n  completionInvalidated: boolean\n}\n\nconst DEFAULT_MAX_TURNS = 16\n\n/** Changing the wording of an unsubmitted conclusion is not execution progress. */\nconst UNVERIFIED_ANSWER_LIMIT = 3\n\n/**\n * Run an agent in basic, self-checking deep, or deep human-in-loop mode.\n *\n * The low-level `turn-*`, trace, commentary, reasoning-summary, and tool events are\n * forwarded unchanged. High-level `agent-*` and `user-input-*` events make GUI\n * orchestration possible without parsing assistant prose.\n */\nexport function runAgent(options: RunAgentOptions): AsyncIterable<AgentRunEvent> {\n  return {\n    async * [Symbol.asyncIterator]() {\n      const queue = new AwaitedEventQueue<AgentRunEvent>()\n      const consumer = new AbortController()\n      const teardownTimeoutMs = positiveFinite(options.teardownTimeoutMs ?? 30_000, 'teardownTimeoutMs')\n      const signal = options.signal === undefined\n        ? consumer.signal\n        : AbortSignal.any([options.signal, consumer.signal])\n      let tail = Promise.resolve()\n      const emit = (event: AgentRunEvent): Promise<void> => {\n        const next = tail.then(() => queue.push(detachedFrozen(event)))\n        tail = next.catch(() => undefined)\n        return next\n      }\n      const task = driveAgent(options, signal, emit)\n        .then(async () => { await tail; queue.close() }, async error => { await tail; queue.fail(error) })\n\n      try {\n        while (true) {\n          const item = await queue.take()\n          if (item.done) break\n          yield item.value\n        }\n        await task\n      } finally {\n        consumer.abort(new Error('agent event consumer stopped'))\n        queue.close()\n        if (!await waitForSettlement(task, teardownTimeoutMs)) {\n          const error = new Error(\n            `agent producer ignored cancellation for more than ${teardownTimeoutMs}ms`,\n            { cause: consumer.signal.reason },\n          ) as Error & { code: string }\n          error.code = 'AGENT_TEARDOWN_TIMEOUT'\n          throw error\n        }\n      }\n    },\n  }\n}\n\nasync function driveAgent(\n  options: RunAgentOptions,\n  signal: AbortSignal,\n  emit: (event: AgentRunEvent) => Promise<void>,\n): Promise<void> {\n  const mode: AgentMode = options.mode ?? 'basic'\n  if (!['basic', 'deep', 'deep-human-in-loop'].includes(mode)) {\n    throw new RangeError(`unsupported agent mode \"${String(mode)}\"`)\n  }\n  const configuredUserInput = 'userInput' in options ? options.userInput : undefined\n  if (mode === 'deep-human-in-loop'\n    && (configuredUserInput === undefined || typeof configuredUserInput.request !== 'function')) {\n    throw new TypeError('deep-human-in-loop mode requires a UserInputBroker')\n  }\n  const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS\n  if (maxTurns !== 'auto' && (!Number.isSafeInteger(maxTurns) || maxTurns < 1)) {\n    throw new RangeError(\"maxTurns must be a positive safe integer or 'auto'\")\n  }\n  await emit({ type: 'agent-start', mode, maxTurns })\n\n  const state: DeepState = {\n    completion: undefined, userAborted: false, unverifiedAnswers: 0, completionInvalidated: false,\n  }\n  const deep = mode !== 'basic'\n  const broker = options.mode === 'deep' || options.mode === 'deep-human-in-loop'\n    ? configuredUserInput\n    : undefined\n  const internalTools: ToolDefinition[] = []\n  // Spilling without a way to read the spill back would be worse than cutting\n  // the output: the model would be told the rest exists and given no way in.\n  if (options.spillStore !== undefined) {\n    internalTools.push(readSpillTool(options.spillStore) as ToolDefinition)\n  }\n  if (deep) internalTools.push(completionTool())\n  if (broker !== undefined && mode !== 'basic') {\n    internalTools.push(userInputTool(mode, broker, state, emit, options.accounting))\n  }\n  const tools = internalTools.length === 0 ? options.tools : combineTools(options.tools, internalTools)\n  const hooks = deep ? deepHooks(options.hooks, options.history, state, maxTurns) : options.hooks\n  const turnOptions: RunTurnOptions = {\n    registry: options.registry,\n    config: options.config,\n    history: options.history,\n    ...tools === undefined ? {} : { tools },\n    ...options.nativeTools === undefined ? {} : { nativeTools: options.nativeTools },\n    ...options.toolChoice === undefined ? {} : { toolChoice: options.toolChoice },\n    ...options.imagePolicy === undefined ? {} : { imagePolicy: options.imagePolicy },\n    ...(options.validateOutput === undefined ? {} : { validateOutput: options.validateOutput }),\n    ...options.outputFormat === undefined ? {} : { outputFormat: options.outputFormat },\n    system: joinSystem(options.system, modeSystem(mode, broker !== undefined)),\n    ...options.interceptors === undefined ? {} : { interceptors: shieldControlTools(options.interceptors) },\n    ...options.approvals === undefined ? {} : { approvals: options.approvals },\n    bounds: { ...options.bounds, maxSteps: maxTurns },\n    ...hooks === undefined ? {} : { hooks },\n    signal,\n    ...options.logger === undefined ? {} : { logger: options.logger },\n    commentary: options.commentary ?? 'concise',\n    teardownTimeoutMs: options.teardownTimeoutMs ?? 30_000,\n    ...options.modelTimeoutMs === undefined ? {} : { modelTimeoutMs: options.modelTimeoutMs },\n    ...options.maxModelRequestBytes === undefined ? {} : { maxModelRequestBytes: options.maxModelRequestBytes },\n    ...options.maxModelResponseBytes === undefined ? {} : { maxModelResponseBytes: options.maxModelResponseBytes },\n    ...options.maxModelStreamEvents === undefined ? {} : { maxModelStreamEvents: options.maxModelStreamEvents },\n    ...options.hookTimeoutMs === undefined ? {} : { hookTimeoutMs: options.hookTimeoutMs },\n    ...options.hookTeardownTimeoutMs === undefined ? {} : { hookTeardownTimeoutMs: options.hookTeardownTimeoutMs },\n    ...options.trace === undefined ? {} : { trace: options.trace },\n    ...options.accounting === undefined ? {} : { accounting: options.accounting },\n    ...options.spillStore === undefined ? {} : { spillStore: options.spillStore },\n    ...options.contextSections === undefined ? {} : { contextSections: options.contextSections },\n  }\n\n  let terminal: TurnOutcome | undefined\n  let stepCalls: string[] = []\n  let completionCandidate: CompletionSubmission | undefined\n  for await (const event of runTurn(turnOptions)) {\n    if (event.type === 'step-start') {\n      stepCalls = []\n      completionCandidate = undefined\n    } else if (event.type === 'tool-call') {\n      stepCalls.push(event.call.toolName)\n      // Work performed after an accepted submission invalidates that submission;\n      // the new result has not yet passed the completion gate.\n      if (event.call.toolName !== AGENT_CONTROL_TOOLS.complete\n        && tools?.get(event.call.toolName)?.completionExempt !== true) {\n        if (state.completion !== undefined) state.completionInvalidated = true\n        state.completion = undefined\n        state.unverifiedAnswers = 0\n      }\n    } else if (event.type === 'tool-result'\n      && event.call.toolName === AGENT_CONTROL_TOOLS.complete\n      && !event.result.isError) {\n      completionCandidate = completionFromResult(event.result.value)\n    } else if (event.type === 'step-end'\n      && completionCandidate !== undefined\n      && stepCalls.filter(name => name === AGENT_CONTROL_TOOLS.complete).length === 1\n      && stepCalls.every(name => name === AGENT_CONTROL_TOOLS.complete || tools?.get(name)?.completionExempt === true)) {\n      // A completion submission cannot share a batch with work whose results the\n      // model had not seen when it claimed success.\n      state.completion = completionCandidate\n      state.completionInvalidated = false\n    }\n    if (event.type === 'turn-end') terminal = event.outcome\n    await emit(event)\n  }\n  if (terminal === undefined) throw new Error('runTurn ended without a turn-end event')\n  const completed = mode === 'basic'\n    ? terminal.reason.kind === 'completed' || terminal.reason.kind === 'concluded-by-tool'\n    : state.completion !== undefined && !state.userAborted\n      && (terminal.reason.kind === 'completed'\n        || terminal.reason.kind === 'concluded-by-tool'\n        || (terminal.reason.kind === 'budget-exhausted' && terminal.reason.forcedFinalAnswer))\n      && terminal.text.trim() !== ''\n  const outcome: AgentRunOutcome = {\n    ...terminal,\n    mode,\n    completed,\n    ...state.completion === undefined ? {} : { completion: state.completion },\n  }\n  await emit({ type: 'agent-end', outcome })\n}\n\nfunction completionTool(): ToolDefinition<CompletionSubmission> {\n  return defineTool({\n    name: AGENT_CONTROL_TOOLS.complete,\n    description: 'Submit the self-check only when the user objective and constraints are fully satisfied. After acceptance, give the user the final answer.',\n    // The one call that ENDS a deep run. A budget that can block it can leave\n    // the run with no way to complete at all.\n    budgetExempt: true,\n    parameters: {\n      type: 'object',\n      properties: {\n        summary: { type: 'string', description: 'Concise statement of what was completed.' },\n        evidence: {\n          type: 'array', items: { type: 'string' },\n          description: 'Concrete checks or tool results showing the objective is satisfied.',\n        },\n      },\n      required: ['summary', 'evidence'],\n      additionalProperties: false,\n    },\n    parse: parseCompletion,\n    execute: submission => ({\n      accepted: true,\n      summary: submission.summary,\n      evidence: [...submission.evidence],\n      instruction: 'This self-check is accepted for the current run. Now provide the substantive final report itself: findings or changes, evidence or sources, checks performed, and remaining limitations. Do not merely say the self-check passed or refer to an earlier message. Do not call submit_result again in this run unless you perform new substantive tool work that invalidates this submission. A later user request or worker follow-up starts a new run and needs its own self-check.',\n    }),\n  })\n}\n\nfunction userInputTool(\n  mode: Exclude<AgentMode, 'basic'>,\n  broker: UserInputBroker,\n  state: DeepState,\n  emit: (event: AgentRunEvent) => Promise<void>,\n  accounting?: RunTurnOptions['accounting'],\n): ToolDefinition<{ readonly questions: readonly UserInputQuestion[] }> {\n  return defineTool({\n    name: AGENT_CONTROL_TOOLS.requestUserInput,\n    // Asking the user is how a blocked run gets unblocked; a spent budget must\n    // not be the reason the question is never asked.\n    budgetExempt: true,\n    description: mode === 'deep-human-in-loop'\n      ? 'Ask the user one to three short questions when a material choice or missing fact requires human input, then wait for the response. Provide 2-3 mutually exclusive suggestions; free-form input is added by the client.'\n      : 'Ask the user one to three short clarification questions only when blocked, then wait for the response. Provide suggested choices; free-form input is added by the client.',\n    parameters: requestUserInputSchema(),\n    parse: parseUserInput,\n    execute: async ({ questions }, ctx) => {\n      const operation = accounting?.startOperation('user-input', {\n        toolCallId: ctx.callId,\n        data: { questionCount: questions.length },\n      })\n      const request: UserInputRequest = {\n        requestId: ctx.callId, callId: ctx.callId, turn: ctx.turn, step: ctx.step,\n        questions, isBlocking: true,\n      }\n      // Start the broker first: an event consumer may resolve synchronously, and\n      // the waiter must already exist when the request event becomes visible.\n      try {\n        const pending = broker.request(request, ctx.signal)\n        await emit({ type: 'user-input-request', request })\n        const response = await pending\n        await emit({ type: 'user-input-response', request, response })\n        if (response === 'abort') {\n          state.userAborted = true\n          ctx.concludeTurn()\n          if (operation !== undefined) accounting?.endOperation(operation, 'aborted')\n          return { aborted: true }\n        }\n        if (operation !== undefined) accounting?.endOperation(operation, 'success')\n        return validateUserResponse(response, questions) as unknown as JsonObject\n      } catch (error) {\n        if (operation !== undefined) accounting?.endOperation(\n          operation,\n          ctx.signal.aborted ? 'aborted' : 'error',\n          { error },\n        )\n        throw error\n      }\n    },\n  })\n}\n\nfunction deepHooks(\n  userHooks: TurnHooks | undefined,\n  history: RunAgentOptions['history'],\n  state: DeepState,\n  maxTurns: number | 'auto',\n): TurnHooks {\n  return {\n    ...userHooks,\n    onTurnEnd: async context => {\n      await userHooks?.onTurnEnd?.(context)\n      if (context.outcome.reason.kind !== 'completed'\n        || (maxTurns !== 'auto' && context.outcome.steps >= maxTurns)\n        || state.completion !== undefined\n        || state.userAborted) return\n      // Auto must not pay indefinitely for paraphrases of \"already checked\".\n      // Substantive tool work resets this allowance; progress-only updates do not.\n      state.unverifiedAnswers++\n      if (state.unverifiedAnswers >= UNVERIFIED_ANSWER_LIMIT) return\n      history.append({ kind: 'user', message: createUserMessage({\n        source: { kind: 'app', producer: 'deep-mode-self-check' },\n        content: [{\n          type: 'text',\n          text: (state.completionInvalidated\n            ? `Your previously accepted submission is no longer current because you called another substantive tool afterwards. Review the later tool results and call ${AGENT_CONTROL_TOOLS.complete} again when complete; the old instruction not to resubmit no longer applies. `\n            : '')\n            + `Self-check required: this run has no accepted current self-check. Acceptance recorded in an earlier run does not complete this request or follow-up; an earlier instruction not to resubmit applied only to that earlier run. Compare the current result against the user's objective and every constraint. If anything is missing, continue with tools. If blocked and request_user_input is available, ask the user. Only when the work is actually complete, call ${AGENT_CONTROL_TOOLS.complete}. Rephrasing a completion claim without submitting does not satisfy this gate.`,\n        }],\n      }) })\n    },\n  }\n}\n\nclass CombinedToolCatalog implements ToolCatalog {\n  private readonly definitions: ReadonlyMap<string, ToolDefinition>\n  constructor(base: ToolCatalog | undefined, additions: readonly ToolDefinition[]) {\n    const definitions = new Map<string, ToolDefinition>()\n    for (const name of base?.names() ?? []) {\n      const definition = base?.get(name)\n      if (definition !== undefined) definitions.set(name, definition)\n    }\n    for (const definition of additions) {\n      if (definitions.has(definition.name)) {\n        throw new Error(`tool name \"${definition.name}\" is reserved by the selected agent mode`)\n      }\n      definitions.set(definition.name, definition)\n    }\n    this.definitions = definitions\n  }\n  get(name: string): ToolDefinition | undefined { return this.definitions.get(name) }\n  has(name: string): boolean { return this.definitions.has(name) }\n  names(): readonly string[] { return [...this.definitions.keys()] }\n  schemas() {\n    return [...this.definitions.values()].map(({ name, description, parameters }) => ({\n      name, description, parameters: structuredClone(parameters),\n    }))\n  }\n  executionMode(name: string, args: unknown): ToolExecutionMode {\n    const definition = this.definitions.get(name)\n    if (definition === undefined) return 'exclusive'\n    try { return definition.isConcurrencySafe?.(args) === true ? 'parallel' : 'exclusive' }\n    catch { return 'exclusive' }\n  }\n}\n\nfunction combineTools(base: ToolCatalog | undefined, additions: readonly ToolDefinition[]): ToolCatalog {\n  return new CombinedToolCatalog(base, additions)\n}\n\n/** Control tools are host protocol, not application capabilities subject to tool policy. */\nfunction shieldControlTools(interceptors: readonly ToolInterceptor[]): readonly ToolInterceptor[] {\n  const reserved = new Set<string>(Object.values(AGENT_CONTROL_TOOLS))\n  return interceptors.map(interceptor => ({\n    name: interceptor.name,\n    ...interceptor.before === undefined ? {} : {\n      before: (call, next) => reserved.has(call.toolName) ? next() : interceptor.before!(call, next),\n    },\n    ...interceptor.around === undefined ? {} : {\n      around: (call, next) => reserved.has(call.toolName) ? next() : interceptor.around!(call, next),\n    },\n    ...interceptor.after === undefined ? {} : {\n      after: (call, result, next) => reserved.has(call.toolName) ? next() : interceptor.after!(call, result, next),\n    },\n  }))\n}\n\nfunction completionFromResult(value: unknown): CompletionSubmission {\n  const result = record(value, 'submit_result result')\n  return parseCompletion({ summary: result.summary, evidence: result.evidence })\n}\n\nfunction validateUserResponse(\n  response: UserInputResponse,\n  questions: readonly UserInputQuestion[],\n): UserInputResponse {\n  const expected = new Set(questions.map(question => question.id))\n  for (const id of expected) {\n    const answer = response.answers[id]\n    if (answer === undefined || !Array.isArray(answer.answers) || answer.answers.length === 0\n      || answer.answers.some(value => typeof value !== 'string' || value.trim().length === 0)) {\n      throw new Error(`the user-input broker returned no valid answer for \"${id}\"`)\n    }\n  }\n  for (const id of Object.keys(response.answers)) {\n    if (!expected.has(id)) throw new Error(`the user-input broker returned an answer for unknown question \"${id}\"`)\n  }\n  return response\n}\n\nfunction parseCompletion(raw: unknown): CompletionSubmission {\n  const value = record(raw, 'submit_result arguments')\n  if (typeof value.summary !== 'string' || value.summary.trim().length === 0) {\n    throw new Error('summary must be a non-empty string')\n  }\n  if (!Array.isArray(value.evidence) || value.evidence.some(item => typeof item !== 'string' || item.trim().length === 0)) {\n    throw new Error('evidence must be an array of non-empty strings')\n  }\n  return { summary: value.summary, evidence: value.evidence as string[] }\n}\n\nfunction parseUserInput(raw: unknown): { readonly questions: readonly UserInputQuestion[] } {\n  const value = record(raw, 'request_user_input arguments')\n  if (!Array.isArray(value.questions) || value.questions.length < 1 || value.questions.length > 3) {\n    throw new Error('questions must contain one to three items')\n  }\n  const ids = new Set<string>()\n  const questions = value.questions.map((rawQuestion, index) => {\n    const question = record(rawQuestion, `questions[${index}]`)\n    const id = requiredString(question.id, `questions[${index}].id`)\n    if (!/^[a-z][a-z0-9_]*$/.test(id)) throw new Error(`questions[${index}].id must be snake_case`)\n    if (ids.has(id)) throw new Error(`question id \"${id}\" is duplicated`)\n    ids.add(id)\n    const header = requiredString(question.header, `questions[${index}].header`)\n    const prompt = requiredString(question.question, `questions[${index}].question`)\n    if (!Array.isArray(question.options) || question.options.length < 2 || question.options.length > 3) {\n      throw new Error(`questions[${index}].options must contain two or three choices`)\n    }\n    const options = question.options.map((rawOption, optionIndex) => {\n      const option = record(rawOption, `questions[${index}].options[${optionIndex}]`)\n      return {\n        label: requiredString(option.label, `questions[${index}].options[${optionIndex}].label`),\n        description: requiredString(option.description, `questions[${index}].options[${optionIndex}].description`),\n      }\n    })\n    return Object.freeze({ id, header, question: prompt, options: Object.freeze(options), allowFreeForm: true as const })\n  })\n  return { questions: Object.freeze(questions) }\n}\n\nfunction requestUserInputSchema(): Record<string, unknown> {\n  return {\n    type: 'object',\n    properties: {\n      questions: {\n        type: 'array', minItems: 1, maxItems: 3,\n        description: 'Questions to show the user. Prefer one and do not exceed three.',\n        items: {\n          type: 'object', additionalProperties: false,\n          properties: {\n            id: { type: 'string', description: 'Stable snake_case answer key.' },\n            header: { type: 'string', description: 'Short UI label, ideally 12 characters or fewer.' },\n            question: { type: 'string', description: 'Single-sentence question.' },\n            options: {\n              type: 'array', minItems: 2, maxItems: 3,\n              description: 'Mutually exclusive choices. Put the recommended choice first and suffix its label with \"(Recommended)\". Do not add Other; the client supplies free-form input.',\n              items: {\n                type: 'object', additionalProperties: false,\n                properties: {\n                  label: { type: 'string', description: 'User-facing label, one to five words.' },\n                  description: { type: 'string', description: 'One sentence explaining impact or trade-off.' },\n                },\n                required: ['label', 'description'],\n              },\n            },\n          },\n          required: ['id', 'header', 'question', 'options'],\n        },\n      },\n    },\n    required: ['questions'],\n    additionalProperties: false,\n  }\n}\n\nfunction modeSystem(mode: AgentMode, canAskUser: boolean): string {\n  if (mode === 'basic') return [\n    'Work as a bounded tool-using agent. Use available tools proactively when they materially improve correctness.',\n    'Stay within the configured iteration budget, then give the best final answer supported by the gathered results.',\n  ].join(' ')\n  const ask = canAskUser\n    ? `If a missing fact or material user choice blocks correct progress, call ${AGENT_CONTROL_TOOLS.requestUserInput} and continue after the answer.`\n    : 'If blocked by missing user input, state that limitation plainly in the final response.'\n  const hil = mode === 'deep-human-in-loop'\n    ? 'For material choices, surface 2-3 concise options with the recommended option first; the UI also permits free-form feedback.'\n    : ''\n  return [\n    'Work autonomously in deep mode. After every tool result, compare the evidence against the user objective and all constraints; continue until gaps are closed.',\n    `Do not treat a plausible draft as completion. When the work is actually complete, call ${AGENT_CONTROL_TOOLS.complete} with a summary and concrete evidence, then provide the final answer.`,\n    ask, hil,\n    'Never reveal private chain-of-thought. Use concise user-visible commentary for intent, progress, observations, and decisions.',\n  ].filter(Boolean).join(' ')\n}\n\nfunction joinSystem(...parts: readonly (string | undefined)[]): string {\n  return parts.filter((part): part is string => part !== undefined && part.length > 0).join('\\n\\n')\n}\n\nfunction record(value: unknown, label: string): Record<string, unknown> {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new Error(`${label} must be an object`)\n  return value as Record<string, unknown>\n}\nfunction requiredString(value: unknown, label: string): string {\n  if (typeof value !== 'string' || value.trim().length === 0) throw new Error(`${label} must be a non-empty string`)\n  return value\n}\nfunction positiveFinite(value: number, name: string): number {\n  if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${name} must be a positive finite number`)\n  return value\n}\n"],"mappings":"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"}

package/dist/agent/mode/user-input.d.ts

@@ -0,0 +1,61 @@
+import { ToolCallId } from "../../primitives/brand.js";
+//#region src/agent/mode/user-input.d.ts
+interface UserInputOption {
+  /** Short text shown on the choice button. */
+  readonly label: string;
+  /** One sentence explaining the consequence or trade-off. */
+  readonly description: string;
+}
+interface UserInputQuestion {
+  /** Stable snake_case key used to map the answer. */
+  readonly id: string;
+  /** Compact UI heading (12 characters or fewer is recommended). */
+  readonly header: string;
+  /** The single question shown to the user. */
+  readonly question: string;
+  /** Two or three mutually exclusive suggestions. Free-form input is separate. */
+  readonly options: readonly UserInputOption[];
+  /** A UI should offer a free-form answer in addition to the suggestions. */
+  readonly allowFreeForm: true;
+}
+interface UserInputRequest {
+  /** The provider tool-call id is the durable correlation id. */
+  readonly requestId: ToolCallId;
+  readonly callId: ToolCallId;
+  readonly turn: number;
+  readonly step: number;
+  readonly questions: readonly UserInputQuestion[];
+  readonly isBlocking: true;
+}
+interface UserInputAnswer {
+  /** One or more selected labels or free-form strings. */
+  readonly answers: readonly string[];
+}
+interface UserInputResponse {
+  /** Answers keyed by {@link UserInputQuestion.id}. */
+  readonly answers: Readonly<Record<string, UserInputAnswer>>;
+}
+type UserInputDecision = UserInputResponse | 'abort';
+interface UserInputBroker {
+  readonly request: (request: UserInputRequest, signal?: AbortSignal) => Promise<UserInputDecision>;
+}
+interface InteractiveUserInputBroker extends UserInputBroker {
+  pending(): readonly UserInputRequest[];
+  onRequest(listener: (request: UserInputRequest) => void): () => void;
+  resolve(requestId: ToolCallId, response: UserInputResponse): boolean;
+  abortAll(): void;
+}
+interface InteractiveUserInputBrokerOptions {
+  /** Maximum requests parked across concurrent sessions. Defaults to 1,024. */
+  readonly maxPending?: number;
+}
+/**
+ * Create a broker for GUIs and CLIs that pause one tool call and resume it by id.
+ * The waiter is installed before listeners run, so a synchronous listener is safe.
+ */
+declare function createUserInputBroker(options?: InteractiveUserInputBrokerOptions): InteractiveUserInputBroker;
+/** A headless broker useful for policy-driven runs and tests. */
+declare function fixedUserInputBroker(response: UserInputResponse | ((request: UserInputRequest) => UserInputDecision | Promise<UserInputDecision>)): UserInputBroker;
+//#endregion
+export { InteractiveUserInputBroker, InteractiveUserInputBrokerOptions, UserInputAnswer, UserInputBroker, UserInputDecision, UserInputOption, UserInputQuestion, UserInputRequest, UserInputResponse, createUserInputBroker, fixedUserInputBroker };
+//# sourceMappingURL=user-input.d.ts.map

package/dist/agent/mode/user-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-input.d.ts","names":[],"sources":["../../../src/agent/mode/user-input.ts"],"mappings":";;UAKiB;;WAEN;;WAEA;;UAGM;;WAEN;;WAEA;;WAEA;;WAEA,kBAAkB;;WAElB;;UAGM;;WAEN,WAAW;WACX,QAAQ;WACR;WACA;WACA,oBAAoB;WACpB;;UAGM;;WAEN;;UAGM;;WAEN,SAAS,SAAS,eAAe;;KAGhC,oBAAoB;UAEf;WACN,UAAU,SAAS,kBAAkB,SAAS,gBAAgB,QAAQ;;UAGhE,mCAAmC;EAClD,oBAAoB;EACpB,UAAU,WAAW,SAAS;EAC9B,QAAQ,WAAW,YAAY,UAAU;EACzC;;UAGe;;WAEN;;;;;;iBAYK,sBAAsB,UAAS,oCAAyC;;iBA8DxE,qBACd,UAAU,sBAAsB,SAAS,qBAAqB,oBAAoB,QAAQ,sBACzF"}

package/dist/agent/mode/user-input.js

@@ -0,0 +1,2 @@
+import{detachedFrozen as e}from"../../primitives/snapshot.js";function t(t={}){let r=n(t.maxPending??1024,`user-input maxPending`),i=new Map,a=new Set;return{request(t,n){if(n?.aborted===!0)return Promise.resolve(`abort`);if(i.has(t.requestId))return Promise.reject(Error(`user-input request '${t.requestId}' is already pending`));if(i.size>=r)return Promise.reject(Error(`user-input broker reached its ${r}-request limit`));let o=e(t);return new Promise(e=>{let r=!1,s=a=>{r||(r=!0,i.delete(t.requestId),n?.removeEventListener(`abort`,c),e(a))};function c(){s(`abort`)}i.set(t.requestId,{request:o,settle:s}),n?.addEventListener(`abort`,c,{once:!0});for(let e of[...a])try{e(o)}catch{}})},pending(){return[...i.values()].map(e=>e.request)},onRequest(e){return a.add(e),()=>void a.delete(e)},resolve(t,n){let r=i.get(t);return r!==void 0&&(r.settle(e(n)),!0)},abortAll(){for(let e of[...i.values()])e.settle(`abort`)}}}function n(e,t){if(!Number.isSafeInteger(e)||e<1)throw RangeError(`${t} must be a positive safe integer`);return e}function r(e){return{request:t=>Promise.resolve(typeof e==`function`?e(t):e)}}export{t as createUserInputBroker,r as fixedUserInputBroker};
+//# sourceMappingURL=user-input.js.map

package/dist/agent/mode/user-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-input.js","names":[],"sources":["../../../src/agent/mode/user-input.ts"],"sourcesContent":["/** Human input as a resumable, call-id-addressed boundary. */\n\nimport type { ToolCallId } from '../../primitives/index.ts'\nimport { detachedFrozen } from '../../primitives/index.ts'\n\nexport interface UserInputOption {\n  /** Short text shown on the choice button. */\n  readonly label: string\n  /** One sentence explaining the consequence or trade-off. */\n  readonly description: string\n}\n\nexport interface UserInputQuestion {\n  /** Stable snake_case key used to map the answer. */\n  readonly id: string\n  /** Compact UI heading (12 characters or fewer is recommended). */\n  readonly header: string\n  /** The single question shown to the user. */\n  readonly question: string\n  /** Two or three mutually exclusive suggestions. Free-form input is separate. */\n  readonly options: readonly UserInputOption[]\n  /** A UI should offer a free-form answer in addition to the suggestions. */\n  readonly allowFreeForm: true\n}\n\nexport interface UserInputRequest {\n  /** The provider tool-call id is the durable correlation id. */\n  readonly requestId: ToolCallId\n  readonly callId: ToolCallId\n  readonly turn: number\n  readonly step: number\n  readonly questions: readonly UserInputQuestion[]\n  readonly isBlocking: true\n}\n\nexport interface UserInputAnswer {\n  /** One or more selected labels or free-form strings. */\n  readonly answers: readonly string[]\n}\n\nexport interface UserInputResponse {\n  /** Answers keyed by {@link UserInputQuestion.id}. */\n  readonly answers: Readonly<Record<string, UserInputAnswer>>\n}\n\nexport type UserInputDecision = UserInputResponse | 'abort'\n\nexport interface UserInputBroker {\n  readonly request: (request: UserInputRequest, signal?: AbortSignal) => Promise<UserInputDecision>\n}\n\nexport interface InteractiveUserInputBroker extends UserInputBroker {\n  pending(): readonly UserInputRequest[]\n  onRequest(listener: (request: UserInputRequest) => void): () => void\n  resolve(requestId: ToolCallId, response: UserInputResponse): boolean\n  abortAll(): void\n}\n\nexport interface InteractiveUserInputBrokerOptions {\n  /** Maximum requests parked across concurrent sessions. Defaults to 1,024. */\n  readonly maxPending?: number\n}\n\ninterface Waiter {\n  readonly request: UserInputRequest\n  readonly settle: (decision: UserInputDecision) => void\n}\n\n/**\n * Create a broker for GUIs and CLIs that pause one tool call and resume it by id.\n * The waiter is installed before listeners run, so a synchronous listener is safe.\n */\nexport function createUserInputBroker(options: InteractiveUserInputBrokerOptions = {}): InteractiveUserInputBroker {\n  const maxPending = positiveSafeInteger(options.maxPending ?? 1_024, 'user-input maxPending')\n  const waiters = new Map<ToolCallId, Waiter>()\n  const listeners = new Set<(request: UserInputRequest) => void>()\n\n  return {\n    request(request, signal) {\n      if (signal?.aborted === true) return Promise.resolve('abort')\n      if (waiters.has(request.requestId)) {\n        return Promise.reject(new Error(`user-input request '${request.requestId}' is already pending`))\n      }\n      if (waiters.size >= maxPending) {\n        return Promise.reject(new Error(`user-input broker reached its ${maxPending}-request limit`))\n      }\n      const published = detachedFrozen(request)\n      return new Promise<UserInputDecision>((resolve) => {\n        let settled = false\n        const settle = (decision: UserInputDecision): void => {\n          if (settled) return\n          settled = true\n          waiters.delete(request.requestId)\n          signal?.removeEventListener('abort', onAbort)\n          resolve(decision)\n        }\n        function onAbort(): void { settle('abort') }\n\n        waiters.set(request.requestId, { request: published, settle })\n        signal?.addEventListener('abort', onAbort, { once: true })\n        for (const listener of [...listeners]) {\n          try { listener(published) } catch { /* observers do not own the waiter */ }\n        }\n      })\n    },\n\n    pending() {\n      return [...waiters.values()].map(waiter => waiter.request)\n    },\n\n    onRequest(listener) {\n      listeners.add(listener)\n      return () => void listeners.delete(listener)\n    },\n\n    resolve(requestId, response) {\n      const waiter = waiters.get(requestId)\n      if (waiter === undefined) return false\n      waiter.settle(detachedFrozen(response))\n      return true\n    },\n\n    abortAll() {\n      for (const waiter of [...waiters.values()]) waiter.settle('abort')\n    },\n  }\n}\n\nfunction positiveSafeInteger(value: number, label: string): number {\n  if (!Number.isSafeInteger(value) || value < 1) throw new RangeError(`${label} must be a positive safe integer`)\n  return value\n}\n\n/** A headless broker useful for policy-driven runs and tests. */\nexport function fixedUserInputBroker(\n  response: UserInputResponse | ((request: UserInputRequest) => UserInputDecision | Promise<UserInputDecision>),\n): UserInputBroker {\n  return {\n    request: request => Promise.resolve(typeof response === 'function' ? response(request) : response),\n  }\n}\n"],"mappings":"8DAwEA,SAAgB,EAAsB,EAA6C,CAAC,EAA+B,CACjH,IAAM,EAAa,EAAoB,EAAQ,YAAc,KAAO,uBAAuB,EACrF,EAAU,IAAI,IACd,EAAY,IAAI,IAEtB,MAAO,CACL,QAAQ,EAAS,EAAQ,CACvB,GAAI,GAAQ,UAAY,GAAM,OAAO,QAAQ,QAAQ,OAAO,EAC5D,GAAI,EAAQ,IAAI,EAAQ,SAAS,EAC/B,OAAO,QAAQ,OAAW,MAAM,uBAAuB,EAAQ,UAAU,qBAAqB,CAAC,EAEjG,GAAI,EAAQ,MAAQ,EAClB,OAAO,QAAQ,OAAW,MAAM,iCAAiC,EAAW,eAAe,CAAC,EAE9F,IAAM,EAAY,EAAe,CAAO,EACxC,OAAO,IAAI,QAA4B,GAAY,CACjD,IAAI,EAAU,GACR,EAAU,GAAsC,CAChD,IACJ,EAAU,GACV,EAAQ,OAAO,EAAQ,SAAS,EAChC,GAAQ,oBAAoB,QAAS,CAAO,EAC5C,EAAQ,CAAQ,EAClB,EACA,SAAS,GAAgB,CAAE,EAAO,OAAO,CAAE,CAE3C,EAAQ,IAAI,EAAQ,UAAW,CAAE,QAAS,EAAW,QAAO,CAAC,EAC7D,GAAQ,iBAAiB,QAAS,EAAS,CAAE,KAAM,EAAK,CAAC,EACzD,IAAK,IAAM,IAAY,CAAC,GAAG,CAAS,EAClC,GAAI,CAAE,EAAS,CAAS,CAAE,MAAQ,CAAwC,CAE9E,CAAC,CACH,EAEA,SAAU,CACR,MAAO,CAAC,GAAG,EAAQ,OAAO,CAAC,CAAC,CAAC,IAAI,GAAU,EAAO,OAAO,CAC3D,EAEA,UAAU,EAAU,CAElB,OADA,EAAU,IAAI,CAAQ,MACT,KAAK,EAAU,OAAO,CAAQ,CAC7C,EAEA,QAAQ,EAAW,EAAU,CAC3B,IAAM,EAAS,EAAQ,IAAI,CAAS,EAGpC,OAFI,IAAW,IAAA,KACf,EAAO,OAAO,EAAe,CAAQ,CAAC,EAC/B,GACT,EAEA,UAAW,CACT,IAAK,IAAM,IAAU,CAAC,GAAG,EAAQ,OAAO,CAAC,EAAG,EAAO,OAAO,OAAO,CACnE,CACF,CACF,CAEA,SAAS,EAAoB,EAAe,EAAuB,CACjE,GAAI,CAAC,OAAO,cAAc,CAAK,GAAK,EAAQ,EAAG,MAAU,WAAW,GAAG,EAAM,iCAAiC,EAC9G,OAAO,CACT,CAGA,SAAgB,EACd,EACiB,CACjB,MAAO,CACL,QAAS,GAAW,QAAQ,QAAQ,OAAO,GAAa,WAAa,EAAS,CAAO,EAAI,CAAQ,CACnG,CACF"}

package/dist/agent/skill/catalog.d.ts

@@ -0,0 +1,53 @@
+import { SkillDefinition, SkillLookupOptions, SkillResourceSummary, SkillSummary } from "./definition.js";
+import { ActivatedSkillSnapshot, RuntimeSkillSource } from "./provider/types.js";
+//#region src/agent/skill/catalog.d.ts
+interface SkillCatalogOptions {
+  /** When present, only these skill ids are visible or loadable. */
+  readonly allowedSkillIds?: readonly string[];
+  readonly maxSkills?: number;
+  readonly maxCatalogBytes?: number;
+}
+declare class SkillCatalog {
+  private readonly sources;
+  private readonly allowedSkillIds;
+  private readonly allowedSkillIdSet;
+  private readonly maxSkills;
+  private readonly maxCatalogBytes;
+  private entries;
+  private visible;
+  private readonly activated;
+  private readonly activatedReferences;
+  private discoveryTail;
+  private discovered;
+  constructor(sources: readonly RuntimeSkillSource[], options?: SkillCatalogOptions);
+  /** Refresh provider metadata. Direct definitions remain available without I/O. */
+  discover(options?: SkillLookupOptions): Promise<readonly SkillSummary[]>;
+  private performDiscovery;
+  /** Last successfully discovered catalog. Direct skills are present immediately. */
+  summaries(): readonly SkillSummary[];
+  /** Load a complete body on demand. Provider definitions are intentionally not cached. */
+  load(id: string, options?: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+  /** Load one selected skill and remember only its small resource manifest. */
+  activate(id: string, options?: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+  isActivated(id: string): boolean;
+  activatedResources(id: string): readonly SkillResourceSummary[] | undefined;
+  /** Activated identities in deterministic catalog order, suitable for session persistence. */
+  activatedSummaries(): readonly SkillSummary[];
+  activatedSkillReferences(): readonly ActivatedSkillSnapshot[];
+  /** Forget conversation-scoped activation without rebuilding provider configuration. */
+  clearActivations(): void;
+  validateReferenceOwner(value: unknown): ActivatedSkillSnapshot;
+  restoreReference(value: unknown, options?: SkillLookupOptions): Promise<SkillDefinition>;
+  /** Read one advertised resource without hydrating the rest of the bundle. */
+  readResource(id: string, path: string, options?: SkillLookupOptions): Promise<string | undefined>;
+  private installDirectSkills;
+  private isAllowed;
+  private providerListOptions;
+  private runtimeLookupOptions;
+  private runtimeProviderListOptions;
+  private resolveRuntimeSkill;
+  private assertAllowedSkillsAvailable;
+}
+//#endregion
+export { SkillCatalog, SkillCatalogOptions };
+//# sourceMappingURL=catalog.d.ts.map

package/dist/agent/skill/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","names":[],"sources":["../../../src/agent/skill/catalog.ts"],"mappings":";;;UAyCiB;;WAEN;WACA;WACA;;cAGE;mBACM;mBACA;mBACA;mBACA;mBACA;UACT;UACA;mBACS;mBACA;UACT;UACA;EAER,YAAY,kBAAkB,sBAAsB,UAAS;;EAsBvD,SAAS,UAAS,qBAA0B,iBAAiB;UAUrD;;EAiEd,sBAAsB;;EAGhB,KAAK,YAAY,UAAS,qBAA0B,QAAQ;;EAmC5D,SAAS,YAAY,UAAS,qBAA0B,QAAQ;EAsBtE,YAAY;EAEZ,mBAAmB,sBAAsB;;EAKzC,+BAA+B;EAI/B,qCAAqC;;EAMrC;EAEA,uBAAuB,iBAAiB;EAQlC,iBAAiB,gBAAgB,UAAS,qBAA0B,QAAQ;;EAwB5E,aACJ,YACA,cACA,UAAS,qBACR;UAwCK;UAcA;UAIA;UAMA;UAQA;UAOA;UASA"}

package/dist/agent/skill/catalog.js

@@ -0,0 +1,2 @@
+import{AgentSdkError as e}from"../../errors/agent-sdk-error.js";import{MAX_SKILL_RESOURCE_CHARS as t,defineSkill as n,skillSummary as r,validateCandidate as i,validateSkillId as a,validateSkillResourcePath as o,validateSkillSource as s}from"./definition.js";import{capabilityIdentityError as c}from"../../errors/capability-identity.js";import{SKILL_ERROR_CODES as l}from"./provider/config.js";import{captureSkillProviderPlugin as u}from"./provider/definition.js";import{skillProviderLogger as d}from"./provider/context.js";import{captureSkillCatalogSnapshot as f,captureSkillReference as p}from"./provider/snapshot.js";var m=class{sources;allowedSkillIds;allowedSkillIdSet;maxSkills;maxCatalogBytes;entries=new Map;visible=Object.freeze([]);activated=new Map;activatedReferences=new Map;discoveryTail=Promise.resolve();discovered=!1;constructor(e,t={}){if(this.maxSkills=j(t.maxSkills??1024,`skill catalog maxSkills`),this.maxCatalogBytes=j(t.maxCatalogBytes??4194304,`skill catalog maxCatalogBytes`),this.sources=v(e),t.allowedSkillIds===void 0)this.allowedSkillIds=void 0,this.allowedSkillIdSet=void 0;else{let e=[...t.allowedSkillIds],n=new Set;for(let t of e){if(a(t,`allowed skill`),n.has(t))throw TypeError(`duplicate allowed skill '${t}'`);n.add(t)}this.allowedSkillIds=Object.freeze(e),this.allowedSkillIdSet=n}this.installDirectSkills()}async discover(e={}){let t=this.discoveryTail,n=M(t,e.signal).then(()=>this.performDiscovery(e));return this.discoveryTail=Promise.allSettled([t,n]).then(()=>void 0),await n}async performDiscovery(e){k(e.signal);let t=new Map,n=0;if(this.allowedSkillIds?.length===0)return this.activated.clear(),this.entries=t,this.visible=Object.freeze([]),this.discovered=!0,this.visible;for(let a of this.sources){if(a.kind===`skill`){if(!this.isAllowed(a.id))continue;if(n=A(n,a,this.maxCatalogBytes),t.size>=this.maxSkills)throw RangeError(`skill catalog exceeds ${this.maxSkills} entries`);w(t,a.id,{summary:r(a),direct:a});continue}if(y(a)){let r=await M(a.list(this.runtimeProviderListOptions(e)),e.signal);k(e.signal);let i=f(a,r,this.maxSkills,this.maxCatalogBytes);for(let e=0;e<i.candidates.length;e++){let r=i.candidates[e];if(this.isAllowed(r.id)){if(n=A(n,r,this.maxCatalogBytes),t.size>=this.maxSkills)throw RangeError(`skill catalog exceeds ${this.maxSkills} entries`);w(t,r.id,{summary:g(r),runtimeProvider:a,reference:i.references[e]})}}continue}let o=await M(a.list(this.providerListOptions(e)),e.signal);if(k(e.signal),o.length>this.maxSkills)throw RangeError(`skill provider '${a.id}' exceeds the ${this.maxSkills}-candidate limit`);for(let e of o)if(i(e,a.id),this.isAllowed(e.id)){if(n=A(n,e,this.maxCatalogBytes),t.size>=this.maxSkills)throw RangeError(`skill catalog exceeds ${this.maxSkills} entries`);w(t,e.id,{summary:h(e),provider:a,candidate:e})}}this.assertAllowedSkillsAvailable(t);for(let e of this.activated.keys()){let n=this.entries.get(e),r=t.get(e);(n===void 0||r===void 0||!E(n,r))&&(this.activated.delete(e),this.activatedReferences.delete(e))}return this.entries=t,this.visible=T(t),this.discovered=!0,this.visible}summaries(){return this.visible}async load(e,t={}){k(t.signal),!this.discovered&&(this.allowedSkillIds!==void 0||this.sources.some(e=>e.kind===`skill-provider`))&&await this.discover(t);let r=this.entries.get(e);if(r?.direct!==void 0)return r.direct;if(r?.runtimeProvider!==void 0&&r.reference!==void 0){let e=await M(r.runtimeProvider.load(r.reference,this.runtimeLookupOptions(t)),t.signal);return k(t.signal),e===void 0?void 0:this.resolveRuntimeSkill(e,r)}if(r?.provider===void 0||r.candidate===void 0)return;let i=await M(r.provider.load(r.candidate,t),t.signal);if(k(t.signal),i===void 0)return;let a=i.resourceBase??r.summary.resourceBase,o=n({...i,source:r.summary.source,provider:r.provider.id,invocation:r.summary.invocation,...a===void 0?{}:{resourceBase:a}});if(o.id!==e)throw TypeError(`skill provider '${r.provider.id}' loaded '${o.id}' for candidate '${e}'`);return o}async activate(e,t={}){!this.discovered&&(this.allowedSkillIds!==void 0||this.sources.some(e=>e.kind===`skill-provider`))&&await this.discover(t);let n=this.entries.get(e),r=await this.load(e,t),i=this.entries.get(e);if(r!==void 0&&(n===void 0||i===void 0||!E(n,i)))throw Error(`skill '${e}' changed while its instructions were loading; load it again`);return r!==void 0&&(this.activated.set(e,r.resourceManifest),i?.reference!==void 0&&this.activatedReferences.set(e,Object.freeze({...i.reference,...r.resourceBase===void 0?{}:{resourceBase:Object.freeze({...r.resourceBase})}}))),r}isActivated(e){return this.activated.has(e)}activatedResources(e){return this.activated.get(e)}activatedSummaries(){return Object.freeze(this.visible.filter(e=>this.activated.has(e.id)))}activatedSkillReferences(){return Object.freeze([...this.activatedReferences.values()].sort((e,t)=>e.id.localeCompare(t.id)))}clearActivations(){this.activated.clear(),this.activatedReferences.clear()}validateReferenceOwner(t){let n=p(t);if(!this.sources.some(e=>y(e)&&e.id===n.provider))throw new e(`Persisted skill reference has no matching provider`,l.REFERENCE_INVALID);return n}async restoreReference(e,t={}){k(t.signal);let n=this.validateReferenceOwner(e),r=this.sources.find(e=>y(e)&&e.id===n.provider);if(r===void 0)throw S();let i=await M(r.load(b(n),this.runtimeLookupOptions(t)),t.signal);if(k(t.signal),i===void 0)throw C();let a={summary:_(i,n),runtimeProvider:r,reference:b(n)},o=this.resolveRuntimeSkill(i,a);if(n.resourceBase?.kind!==o.resourceBase?.kind||n.resourceBase?.value!==o.resourceBase?.value)throw C();return this.entries.set(n.id,a),this.visible=T(this.entries),this.activated.set(n.id,o.resourceManifest),this.activatedReferences.set(n.id,n),o}async readResource(e,n,r={}){if(k(r.signal),o(n,e),!this.isActivated(e))throw Error(`skill '${e}' must be activated before reading resources`);let i=this.entries.get(e),a=i?.direct,s=this.activated.get(e);if(a===void 0&&(s===void 0||i?.provider?.readResource===void 0)&&(a=await this.load(e,r)),a!==void 0&&a.id!==e)throw TypeError(`loaded skill '${a.id}' does not match '${e}'`);let c=a?.resourceManifest??s;if(c===void 0||!c.some(e=>e.path===n))return;let l=a?.resources[n];if(l!==void 0)return l;if(i?.runtimeProvider!==void 0&&i.reference!==void 0)return i.runtimeProvider.readResource===void 0?void 0:x(await M(i.runtimeProvider.readResource(i.reference,n,this.runtimeLookupOptions(r)),r.signal),n);if(i?.provider?.readResource===void 0||i.candidate===void 0)return;let u=await M(i.provider.readResource(i.candidate,n,r),r.signal);if(u!==void 0){if(typeof u!=`string`)throw TypeError(`skill provider '${i.provider.id}' returned a non-text resource '${n}'`);if(u.length>4e4)throw RangeError(`skill resource '${n}' exceeds ${t} characters`);return u}}installDirectSkills(){let e=new Map,t=0;for(let n of this.sources)if(n.kind===`skill`&&this.isAllowed(n.id)){if(t=A(t,n,this.maxCatalogBytes),e.size>=this.maxSkills)throw RangeError(`skill catalog exceeds ${this.maxSkills} entries`);w(e,n.id,{summary:r(n),direct:n})}this.entries=e,this.visible=T(e)}isAllowed(e){return this.allowedSkillIdSet?.has(e)??!0}providerListOptions(e){return this.allowedSkillIds===void 0?e:{...e,allowedSkillIds:this.allowedSkillIds}}runtimeLookupOptions(e){return Object.freeze({...e.cwd===void 0?{}:{cwd:e.cwd},signal:e.signal??new AbortController().signal,logger:d(this)})}runtimeProviderListOptions(e){return Object.freeze({...this.runtimeLookupOptions(e),...this.allowedSkillIds===void 0?{}:{allowedSkillIds:this.allowedSkillIds}})}resolveRuntimeSkill(e,t){let r=t.reference;if(r===void 0)throw S();let i=n({...e,id:r.id,source:r.source,provider:r.provider,invocation:t.summary.invocation});if(e.id!==r.id)throw C();return i}assertAllowedSkillsAvailable(e){if(this.allowedSkillIds===void 0)return;let t=this.allowedSkillIds.filter(t=>!e.has(t));if(t.length>0)throw Error(`configured skill${t.length===1?``:`s`} not available: ${t.join(`, `)}`)}};function h(e){return Object.freeze({id:e.id,name:e.name,description:e.description,...e.whenToUse===void 0?{}:{whenToUse:e.whenToUse},invocation:Object.freeze({...e.invocation}),source:e.source,provider:e.provider,...e.resourceBase===void 0?{}:{resourceBase:e.resourceBase}})}function g(e){return Object.freeze({id:e.id,name:e.name,description:e.description,...e.whenToUse===void 0?{}:{whenToUse:e.whenToUse},invocation:e.invocation??Object.freeze({modelInvocable:!0,userInvocable:!0}),source:e.source,provider:e.provider})}function _(e,t){return r(n({...e,id:t.id,source:t.source,provider:t.provider}))}function v(e){let t=e.map(e=>{if(e.kind===`skill`)return s(e),e;let t=Object.getOwnPropertyDescriptor(e,`apiVersion`);if(t===void 0)return s(e),e;if(!(`value`in t))throw S();return u(e)}),n=new Map;for(let[e,r]of t.entries()){if(r.kind===`skill`)continue;let t=n.get(r.id);if(t!==void 0)throw c(`SKILL_PROVIDER_ID_CONFLICT`,`skill-provider-id`,t,e);n.set(r.id,e)}return Object.freeze(t)}function y(e){return e.kind===`skill-provider`&&Object.getOwnPropertyDescriptor(e,`apiVersion`)?.value===1}function b(e){return Object.freeze({id:e.id,source:e.source,provider:e.provider,catalogRevision:e.catalogRevision,...e.locator===void 0?{}:{locator:e.locator}})}function x(e,n){if(e!==void 0){if(typeof e!=`string`)throw TypeError(`skill provider returned a non-text resource '${n}'`);if(e.length>4e4)throw RangeError(`skill resource '${n}' exceeds ${t} characters`);return e}}function S(){return new e(`Persisted skill reference is invalid`,l.REFERENCE_INVALID)}function C(){return new e(`Persisted skill reference is unavailable`,l.REFERENCE_UNAVAILABLE)}function w(e,t,n){if(e.get(t)!==void 0)throw c(`SKILL_ID_CONFLICT`,`skill-id`,[...e.keys()].indexOf(t),e.size);e.set(t,n)}function T(e){return Object.freeze([...e.values()].map(e=>e.summary).sort((e,t)=>e.id.localeCompare(t.id)))}function E(e,t){if(e.direct!==void 0||t.direct!==void 0)return e.direct===t.direct;if(e.provider!==t.provider)return!1;if(e.runtimeProvider!==void 0||t.runtimeProvider!==void 0)return e.runtimeProvider===t.runtimeProvider&&e.reference?.id===t.reference?.id&&e.reference?.source===t.reference?.source&&e.reference?.provider===t.reference?.provider&&e.reference?.catalogRevision===t.reference?.catalogRevision&&O(e.reference?.locator,t.reference?.locator);if(!D(e.summary,t.summary))return!1;let n=e.candidate,r=t.candidate;return n===void 0||r===void 0?n===r:n.path===r.path&&O(n.locator,r.locator)&&O(n.metadata,r.metadata)}function D(e,t){return e.id===t.id&&e.name===t.name&&e.description===t.description&&e.whenToUse===t.whenToUse&&e.source===t.source&&e.provider===t.provider&&e.invocation.modelInvocable===t.invocation.modelInvocable&&e.invocation.userInvocable===t.invocation.userInvocable&&e.resourceBase?.kind===t.resourceBase?.kind&&e.resourceBase?.value===t.resourceBase?.value}function O(e,t){let n=[[e,t]],r=new WeakMap,i=0;try{for(;n.length>0;){let e=n.pop();if(e===void 0)break;let[t,a]=e;if(Object.is(t,a))continue;if(typeof t!=`object`||!t||typeof a!=`object`||!a||++i>2048)return!1;let o=r.get(t);if(o?.has(a)===!0)continue;if(o===void 0&&(o=new WeakSet,r.set(t,o)),o.add(a),Array.isArray(t)||Array.isArray(a)){if(!Array.isArray(t)||!Array.isArray(a)||t.length!==a.length)return!1;for(let e=0;e<t.length;e++)n.push([t[e],a[e]]);continue}let s=Object.getPrototypeOf(t);if(s!==Object.getPrototypeOf(a)||s!==Object.prototype&&s!==null)return!1;let c=t,l=a,u=Object.keys(c).sort(),d=Object.keys(l).sort();if(u.length!==d.length||u.some((e,t)=>e!==d[t]))return!1;for(let e of u)n.push([c[e],l[e]])}return!0}catch{return!1}}function k(e){if(e?.aborted===!0)throw e.reason??Error(`skill discovery aborted`)}function A(e,t,n){let r=JSON.stringify(t);if(r===void 0)throw TypeError(`skill catalog entry is not JSON serializable`);let i=e+new TextEncoder().encode(r).byteLength;if(i>n)throw RangeError(`skill catalog exceeds ${n} serialized bytes`);return i}function j(e,t){if(!Number.isSafeInteger(e)||e<1)throw RangeError(`${t} must be a positive safe integer`);return e}function M(e,t){return t===void 0?e:(k(t),new Promise((n,r)=>{let i=()=>{a(),r(t.reason??Error(`skill discovery aborted`))},a=()=>{t.removeEventListener(`abort`,i)};t.addEventListener(`abort`,i,{once:!0}),e.then(e=>{a(),n(e)},e=>{a(),r(e)})}))}export{m as SkillCatalog};
+//# sourceMappingURL=catalog.js.map