@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/dist/core/human-input.d.ts

@@ -0,0 +1,100 @@
+import type { SessionEntry, SessionManager } from "@caupulican/pi-agent-core/node";
+import type { ImageContent } from "@caupulican/pi-ai";
+import type { ArtifactStore } from "./context/context-artifacts.ts";
+import type { ContextArtifactRef } from "./context/context-item.ts";
+import type { SessionImageStore } from "./session-image-store.ts";
+import { type SessionBranchEntrySource } from "./session-snapshot.ts";
+export declare const HUMAN_INPUT_CUSTOM_TYPE = "human_input_request";
+export declare const HUMAN_INPUT_WORKER_RESPONSE_CUSTOM_TYPE = "worker-owner-response";
+export declare const HUMAN_INPUT_INLINE_BYTES: number;
+export interface HumanInputOption {
+    label: string;
+    description: string;
+}
+export interface HumanInputQuestion {
+    id: string;
+    header: string;
+    question: string;
+    options: readonly HumanInputOption[];
+    multiSelect?: boolean;
+}
+export interface HumanInputAnswerImage {
+    label: string;
+    mimeType: string;
+}
+export interface HumanInputAnswer {
+    id: string;
+    header: string;
+    question: string;
+    selected: readonly string[];
+    /** Inline answer, or a bounded preview when customArtifact is present. */
+    custom?: string;
+    /** Exact full answer retained out of prompt context when it exceeds the inline bound. */
+    customArtifact?: ContextArtifactRef;
+    images?: readonly HumanInputAnswerImage[];
+    skipped: boolean;
+}
+export type HumanInputStopReason = "user_cancelled" | "ui_unavailable" | "interrupted" | "invalid_questions";
+export interface HumanInputPresentationRequest {
+    requestId: string;
+    questions: readonly HumanInputQuestion[];
+    acceptsImages: boolean;
+}
+export interface HumanInputPresentationResult {
+    answers: readonly HumanInputAnswer[];
+    cancelled: boolean;
+    reason?: HumanInputStopReason;
+    imageContents: readonly ImageContent[];
+}
+export type HumanInputSource = "tool" | "worker";
+export interface HumanInputRequest {
+    requestId: string;
+    source: HumanInputSource;
+    toolCallId?: string;
+    toolName?: string;
+    workerRequestId?: string;
+    questions: readonly HumanInputQuestion[];
+    acceptsImages: boolean;
+    createdAt: string;
+}
+export type HumanInputStatus = "pending" | "answered" | "cancelled";
+export interface HumanInputSnapshot {
+    request: HumanInputRequest;
+    status: HumanInputStatus;
+    answers: readonly HumanInputAnswer[];
+    reason?: HumanInputStopReason;
+    updatedAt: string;
+}
+export interface HumanInputRequestOptions {
+    source: HumanInputSource;
+    toolCallId?: string;
+    toolName?: string;
+    workerRequestId?: string;
+    questions: readonly HumanInputQuestion[];
+    acceptsImages: boolean;
+    now?: () => string;
+}
+export interface ResolveHumanInputOptions {
+    sessionManager: Pick<SessionManager, "appendCustomEntry">;
+    request: HumanInputRequest;
+    present: (request: HumanInputPresentationRequest, options?: {
+        signal?: AbortSignal;
+    }) => Promise<HumanInputPresentationResult>;
+    artifactStore?: ArtifactStore;
+    getImageStore?: () => Pick<SessionImageStore, "retainContent"> | undefined;
+    signal?: AbortSignal;
+    now?: () => string;
+}
+export declare function createHumanInputRequest(options: HumanInputRequestOptions): HumanInputRequest;
+export declare function appendHumanInputSnapshot(sessionManager: Pick<SessionManager, "appendCustomEntry">, snapshot: HumanInputSnapshot): string;
+export declare function beginHumanInputRequest(sessionManager: Pick<SessionManager, "appendCustomEntry">, request: HumanInputRequest): HumanInputSnapshot;
+export declare function getHumanInputSnapshots(entries: readonly SessionEntry[]): HumanInputSnapshot[];
+export declare function getLatestHumanInputSnapshots(source: SessionBranchEntrySource): HumanInputSnapshot[];
+export declare function getWorkerHumanInputsRequiringDelivery(source: SessionBranchEntrySource): HumanInputSnapshot[];
+export declare function getResumableHumanInputSnapshot(source: SessionBranchEntrySource): HumanInputSnapshot | undefined;
+export declare function resolveHumanInput(options: ResolveHumanInputOptions): Promise<{
+    snapshot: HumanInputSnapshot;
+    imageContents: readonly ImageContent[];
+}>;
+export declare function formatHumanInputAnswerText(snapshot: HumanInputSnapshot): string;
+//# sourceMappingURL=human-input.d.ts.map

package/dist/core/human-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-input.d.ts","sourceRoot":"","sources":["../../src/core/human-input.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { ImageContent } from \"@caupulican/pi-ai\";\nimport type { ArtifactStore } from \"./context/context-artifacts.ts\";\nimport type { ContextArtifactRef } from \"./context/context-item.ts\";\nimport type { SessionImageStore } from \"./session-image-store.ts\";\nimport { getActiveSessionBranchEntries, type SessionBranchEntrySource } from \"./session-snapshot.ts\";\nimport { isPlainRecord } from \"./util/value-guards.ts\";\n\nexport const HUMAN_INPUT_CUSTOM_TYPE = \"human_input_request\";\nexport const HUMAN_INPUT_WORKER_RESPONSE_CUSTOM_TYPE = \"worker-owner-response\";\nexport const HUMAN_INPUT_INLINE_BYTES = 16 * 1024;\nconst HUMAN_INPUT_PREVIEW_CHARS = 4_000;\n\nexport interface HumanInputOption {\n\tlabel: string;\n\tdescription: string;\n}\n\nexport interface HumanInputQuestion {\n\tid: string;\n\theader: string;\n\tquestion: string;\n\toptions: readonly HumanInputOption[];\n\tmultiSelect?: boolean;\n}\n\nexport interface HumanInputAnswerImage {\n\tlabel: string;\n\tmimeType: string;\n}\n\nexport interface HumanInputAnswer {\n\tid: string;\n\theader: string;\n\tquestion: string;\n\tselected: readonly string[];\n\t/** Inline answer, or a bounded preview when customArtifact is present. */\n\tcustom?: string;\n\t/** Exact full answer retained out of prompt context when it exceeds the inline bound. */\n\tcustomArtifact?: ContextArtifactRef;\n\timages?: readonly HumanInputAnswerImage[];\n\tskipped: boolean;\n}\n\nexport type HumanInputStopReason = \"user_cancelled\" | \"ui_unavailable\" | \"interrupted\" | \"invalid_questions\";\n\nexport interface HumanInputPresentationRequest {\n\trequestId: string;\n\tquestions: readonly HumanInputQuestion[];\n\tacceptsImages: boolean;\n}\n\nexport interface HumanInputPresentationResult {\n\tanswers: readonly HumanInputAnswer[];\n\tcancelled: boolean;\n\treason?: HumanInputStopReason;\n\timageContents: readonly ImageContent[];\n}\n\nexport type HumanInputSource = \"tool\" | \"worker\";\n\nexport interface HumanInputRequest {\n\trequestId: string;\n\tsource: HumanInputSource;\n\ttoolCallId?: string;\n\ttoolName?: string;\n\tworkerRequestId?: string;\n\tquestions: readonly HumanInputQuestion[];\n\tacceptsImages: boolean;\n\tcreatedAt: string;\n}\n\nexport type HumanInputStatus = \"pending\" | \"answered\" | \"cancelled\";\n\nexport interface HumanInputSnapshot {\n\trequest: HumanInputRequest;\n\tstatus: HumanInputStatus;\n\tanswers: readonly HumanInputAnswer[];\n\treason?: HumanInputStopReason;\n\tupdatedAt: string;\n}\n\ninterface HumanInputSnapshotPayload {\n\tversion: 1;\n\tsnapshot: HumanInputSnapshot;\n}\n\nexport interface HumanInputRequestOptions {\n\tsource: HumanInputSource;\n\ttoolCallId?: string;\n\ttoolName?: string;\n\tworkerRequestId?: string;\n\tquestions: readonly HumanInputQuestion[];\n\tacceptsImages: boolean;\n\tnow?: () => string;\n}\n\nexport interface ResolveHumanInputOptions {\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">;\n\trequest: HumanInputRequest;\n\tpresent: (\n\t\trequest: HumanInputPresentationRequest,\n\t\toptions?: { signal?: AbortSignal },\n\t) => Promise<HumanInputPresentationResult>;\n\tartifactStore?: ArtifactStore;\n\tgetImageStore?: () => Pick<SessionImageStore, \"retainContent\"> | undefined;\n\tsignal?: AbortSignal;\n\tnow?: () => string;\n}\n\nfunction cloneQuestion(question: HumanInputQuestion): HumanInputQuestion {\n\treturn {\n\t\t...question,\n\t\toptions: question.options.map((option) => ({ ...option })),\n\t};\n}\n\nfunction cloneAnswer(answer: HumanInputAnswer): HumanInputAnswer {\n\treturn {\n\t\t...answer,\n\t\tselected: [...answer.selected],\n\t\tcustomArtifact: answer.customArtifact ? { ...answer.customArtifact } : undefined,\n\t\timages: answer.images?.map((image) => ({ ...image })),\n\t};\n}\n\nfunction cloneRequest(request: HumanInputRequest): HumanInputRequest {\n\treturn {\n\t\t...request,\n\t\tquestions: request.questions.map(cloneQuestion),\n\t};\n}\n\nfunction cloneSnapshot(snapshot: HumanInputSnapshot): HumanInputSnapshot {\n\treturn {\n\t\t...snapshot,\n\t\trequest: cloneRequest(snapshot.request),\n\t\tanswers: snapshot.answers.map(cloneAnswer),\n\t};\n}\n\nfunction isStringArray(value: unknown): value is string[] {\n\treturn Array.isArray(value) && value.every((entry) => typeof entry === \"string\");\n}\n\nfunction isQuestion(value: unknown): value is HumanInputQuestion {\n\tif (!isPlainRecord(value) || !Array.isArray(value.options)) return false;\n\treturn (\n\t\ttypeof value.id === \"string\" &&\n\t\ttypeof value.header === \"string\" &&\n\t\ttypeof value.question === \"string\" &&\n\t\t(value.multiSelect === undefined || typeof value.multiSelect === \"boolean\") &&\n\t\tvalue.options.every(\n\t\t\t(option) =>\n\t\t\t\tisPlainRecord(option) && typeof option.label === \"string\" && typeof option.description === \"string\",\n\t\t)\n\t);\n}\n\nfunction isArtifactRef(value: unknown): value is ContextArtifactRef {\n\treturn (\n\t\tisPlainRecord(value) &&\n\t\ttypeof value.id === \"string\" &&\n\t\ttypeof value.kind === \"string\" &&\n\t\ttypeof value.byteLength === \"number\" &&\n\t\ttypeof value.createdAtTurn === \"number\" &&\n\t\ttypeof value.reproducible === \"boolean\"\n\t);\n}\n\nfunction isAnswer(value: unknown): value is HumanInputAnswer {\n\tif (!isPlainRecord(value)) return false;\n\treturn (\n\t\ttypeof value.id === \"string\" &&\n\t\ttypeof value.header === \"string\" &&\n\t\ttypeof value.question === \"string\" &&\n\t\tisStringArray(value.selected) &&\n\t\t(value.custom === undefined || typeof value.custom === \"string\") &&\n\t\t(value.customArtifact === undefined || isArtifactRef(value.customArtifact)) &&\n\t\t(value.images === undefined ||\n\t\t\t(Array.isArray(value.images) &&\n\t\t\t\tvalue.images.every(\n\t\t\t\t\t(image) => isPlainRecord(image) && typeof image.label === \"string\" && typeof image.mimeType === \"string\",\n\t\t\t\t))) &&\n\t\ttypeof value.skipped === \"boolean\"\n\t);\n}\n\nfunction isImageContent(value: unknown): value is ImageContent {\n\treturn (\n\t\tisPlainRecord(value) &&\n\t\tvalue.type === \"image\" &&\n\t\ttypeof value.data === \"string\" &&\n\t\ttypeof value.mimeType === \"string\"\n\t);\n}\n\nfunction normalizePresentationResult(request: HumanInputRequest, value: unknown): HumanInputPresentationResult {\n\tif (!isPlainRecord(value) || typeof value.cancelled !== \"boolean\") {\n\t\tthrow new Error(\"Invalid human-input response: expected a typed presentation result\");\n\t}\n\tif (value.cancelled) {\n\t\tconst reason = value.reason;\n\t\tif (\n\t\t\treason !== undefined &&\n\t\t\treason !== \"user_cancelled\" &&\n\t\t\treason !== \"ui_unavailable\" &&\n\t\t\treason !== \"interrupted\" &&\n\t\t\treason !== \"invalid_questions\"\n\t\t) {\n\t\t\tthrow new Error(\"Invalid human-input response: unknown cancellation reason\");\n\t\t}\n\t\treturn {\n\t\t\tanswers: [],\n\t\t\tcancelled: true,\n\t\t\t...(reason ? { reason } : {}),\n\t\t\timageContents: [],\n\t\t};\n\t}\n\tif (!Array.isArray(value.answers) || !Array.isArray(value.imageContents)) {\n\t\tthrow new Error(\"Invalid human-input response: answers and imageContents must be arrays\");\n\t}\n\tconst answersById = new Map<string, HumanInputAnswer>();\n\tfor (const candidate of value.answers) {\n\t\tif (!isAnswer(candidate)) throw new Error(\"Invalid human-input response: malformed answer\");\n\t\tif (candidate.customArtifact !== undefined) {\n\t\t\tthrow new Error(\"Invalid human-input response: artifact references are harness-owned\");\n\t\t}\n\t\tif (answersById.has(candidate.id)) {\n\t\t\tthrow new Error(`Invalid human-input response: duplicate answer '${candidate.id}'`);\n\t\t}\n\t\tanswersById.set(candidate.id, candidate);\n\t}\n\tif (answersById.size !== request.questions.length) {\n\t\tthrow new Error(\"Invalid human-input response: every question must have exactly one answer\");\n\t}\n\n\tconst answers = request.questions.map((question) => {\n\t\tconst answer = answersById.get(question.id);\n\t\tif (!answer) throw new Error(`Invalid human-input response: missing answer '${question.id}'`);\n\t\tconst optionLabels = new Set(question.options.map((option) => option.label));\n\t\tif (new Set(answer.selected).size !== answer.selected.length) {\n\t\t\tthrow new Error(`Invalid human-input response: duplicate option for '${question.id}'`);\n\t\t}\n\t\tif (answer.selected.some((selection) => !optionLabels.has(selection))) {\n\t\t\tthrow new Error(`Invalid human-input response: unknown option for '${question.id}'`);\n\t\t}\n\t\tif (!question.multiSelect && answer.selected.length > 1) {\n\t\t\tthrow new Error(`Invalid human-input response: '${question.id}' is single-select`);\n\t\t}\n\t\tif (\n\t\t\tanswer.skipped &&\n\t\t\t(answer.selected.length > 0 || Boolean(answer.custom) || (answer.images?.length ?? 0) > 0)\n\t\t) {\n\t\t\tthrow new Error(`Invalid human-input response: skipped answer '${question.id}' contains a value`);\n\t\t}\n\t\treturn {\n\t\t\t...cloneAnswer(answer),\n\t\t\theader: question.header,\n\t\t\tquestion: question.question,\n\t\t};\n\t});\n\tif (!value.imageContents.every(isImageContent)) {\n\t\tthrow new Error(\"Invalid human-input response: malformed image content\");\n\t}\n\tconst answerImages = answers.flatMap((answer) => answer.images ?? []);\n\tif (answerImages.length !== value.imageContents.length) {\n\t\tthrow new Error(\"Invalid human-input response: image metadata does not match image content\");\n\t}\n\tif (!request.acceptsImages && value.imageContents.length > 0) {\n\t\tthrow new Error(\"Invalid human-input response: the selected model does not accept images\");\n\t}\n\tfor (let index = 0; index < answerImages.length; index++) {\n\t\tif (answerImages[index]?.mimeType !== value.imageContents[index]?.mimeType) {\n\t\t\tthrow new Error(\"Invalid human-input response: image MIME metadata does not match image content\");\n\t\t}\n\t}\n\treturn {\n\t\tanswers,\n\t\tcancelled: false,\n\t\timageContents: value.imageContents.map((image) => ({ ...image })),\n\t};\n}\n\nfunction persistPresentationImages(\n\tresult: HumanInputPresentationResult,\n\timageStore: Pick<SessionImageStore, \"retainContent\"> | undefined,\n): HumanInputPresentationResult {\n\tif (!imageStore || result.cancelled || result.imageContents.length === 0) return result;\n\tlet imageIndex = 0;\n\tconst durableContents: ImageContent[] = [];\n\tconst answers = result.answers.map((answer) => {\n\t\tlet custom = answer.custom;\n\t\tconst images = answer.images?.map((image) => {\n\t\t\tconst content = result.imageContents[imageIndex++];\n\t\t\tif (!content) throw new Error(\"Human-input image metadata exceeds supplied image content\");\n\t\t\tconst sequenceMatch = /^\\[Image #(\\d{1,6})\\]$/iu.exec(image.label);\n\t\t\tconst stored = imageStore.retainContent(content, sequenceMatch ? Number(sequenceMatch[1]) : undefined);\n\t\t\tconst durableLabel = `[Image #${stored.sequence}]`;\n\t\t\tif (custom?.includes(image.label)) custom = custom.split(image.label).join(durableLabel);\n\t\t\tdurableContents.push({\n\t\t\t\ttype: \"image\",\n\t\t\t\tdata: Buffer.from(stored.bytes).toString(\"base64\"),\n\t\t\t\tmimeType: stored.mimeType,\n\t\t\t});\n\t\t\treturn { label: durableLabel, mimeType: stored.mimeType };\n\t\t});\n\t\treturn {\n\t\t\t...cloneAnswer(answer),\n\t\t\t...(custom !== undefined ? { custom } : {}),\n\t\t\t...(images && images.length > 0 ? { images } : {}),\n\t\t};\n\t});\n\treturn { ...result, answers, imageContents: durableContents };\n}\n\nfunction isRequest(value: unknown): value is HumanInputRequest {\n\tif (!isPlainRecord(value) || !Array.isArray(value.questions)) return false;\n\treturn (\n\t\ttypeof value.requestId === \"string\" &&\n\t\t(value.source === \"tool\" || value.source === \"worker\") &&\n\t\t(value.toolCallId === undefined || typeof value.toolCallId === \"string\") &&\n\t\t(value.toolName === undefined || typeof value.toolName === \"string\") &&\n\t\t(value.workerRequestId === undefined || typeof value.workerRequestId === \"string\") &&\n\t\tvalue.questions.every(isQuestion) &&\n\t\ttypeof value.acceptsImages === \"boolean\" &&\n\t\ttypeof value.createdAt === \"string\"\n\t);\n}\n\nfunction decodeSnapshot(data: unknown): HumanInputSnapshot | undefined {\n\tif (!isPlainRecord(data) || data.version !== 1 || !isPlainRecord(data.snapshot)) return undefined;\n\tconst snapshot = data.snapshot;\n\tif (\n\t\t!isRequest(snapshot.request) ||\n\t\t(snapshot.status !== \"pending\" && snapshot.status !== \"answered\" && snapshot.status !== \"cancelled\") ||\n\t\t!Array.isArray(snapshot.answers) ||\n\t\t!snapshot.answers.every(isAnswer) ||\n\t\t(snapshot.reason !== undefined &&\n\t\t\tsnapshot.reason !== \"user_cancelled\" &&\n\t\t\tsnapshot.reason !== \"ui_unavailable\" &&\n\t\t\tsnapshot.reason !== \"interrupted\" &&\n\t\t\tsnapshot.reason !== \"invalid_questions\") ||\n\t\ttypeof snapshot.updatedAt !== \"string\"\n\t) {\n\t\treturn undefined;\n\t}\n\treturn cloneSnapshot(snapshot as unknown as HumanInputSnapshot);\n}\n\nexport function createHumanInputRequest(options: HumanInputRequestOptions): HumanInputRequest {\n\tconst now = options.now?.() ?? new Date().toISOString();\n\treturn {\n\t\trequestId: `human-input:${options.toolCallId ?? options.workerRequestId ?? randomUUID()}`,\n\t\tsource: options.source,\n\t\t...(options.toolCallId ? { toolCallId: options.toolCallId } : {}),\n\t\t...(options.toolName ? { toolName: options.toolName } : {}),\n\t\t...(options.workerRequestId ? { workerRequestId: options.workerRequestId } : {}),\n\t\tquestions: options.questions.map(cloneQuestion),\n\t\tacceptsImages: options.acceptsImages,\n\t\tcreatedAt: now,\n\t};\n}\n\nexport function appendHumanInputSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tsnapshot: HumanInputSnapshot,\n): string {\n\tconst payload: HumanInputSnapshotPayload = { version: 1, snapshot: cloneSnapshot(snapshot) };\n\treturn sessionManager.appendCustomEntry(HUMAN_INPUT_CUSTOM_TYPE, payload);\n}\n\nexport function beginHumanInputRequest(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\trequest: HumanInputRequest,\n): HumanInputSnapshot {\n\tconst snapshot: HumanInputSnapshot = {\n\t\trequest: cloneRequest(request),\n\t\tstatus: \"pending\",\n\t\tanswers: [],\n\t\tupdatedAt: request.createdAt,\n\t};\n\tappendHumanInputSnapshot(sessionManager, snapshot);\n\treturn snapshot;\n}\n\nexport function getHumanInputSnapshots(entries: readonly SessionEntry[]): HumanInputSnapshot[] {\n\tconst snapshots: HumanInputSnapshot[] = [];\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== HUMAN_INPUT_CUSTOM_TYPE) continue;\n\t\tconst snapshot = decodeSnapshot(entry.data);\n\t\tif (snapshot) snapshots.push(snapshot);\n\t}\n\treturn snapshots;\n}\n\nexport function getLatestHumanInputSnapshots(source: SessionBranchEntrySource): HumanInputSnapshot[] {\n\tconst latest = new Map<string, HumanInputSnapshot>();\n\tfor (const snapshot of getHumanInputSnapshots(getActiveSessionBranchEntries(source))) {\n\t\tlatest.set(snapshot.request.requestId, snapshot);\n\t}\n\treturn [...latest.values()];\n}\n\nexport function getWorkerHumanInputsRequiringDelivery(source: SessionBranchEntrySource): HumanInputSnapshot[] {\n\tconst entries = getActiveSessionBranchEntries(source);\n\tconst deliveredRequestIds = new Set(\n\t\tentries.flatMap((entry) => {\n\t\t\tif (\n\t\t\t\tentry.type !== \"custom_message\" ||\n\t\t\t\tentry.customType !== HUMAN_INPUT_WORKER_RESPONSE_CUSTOM_TYPE ||\n\t\t\t\t!isPlainRecord(entry.details) ||\n\t\t\t\ttypeof entry.details.requestId !== \"string\"\n\t\t\t) {\n\t\t\t\treturn [];\n\t\t\t}\n\t\t\treturn [entry.details.requestId];\n\t\t}),\n\t);\n\treturn getLatestHumanInputSnapshots(source)\n\t\t.filter(\n\t\t\t(snapshot) => snapshot.request.source === \"worker\" && !deliveredRequestIds.has(snapshot.request.requestId),\n\t\t)\n\t\t.sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));\n}\n\nexport function getResumableHumanInputSnapshot(source: SessionBranchEntrySource): HumanInputSnapshot | undefined {\n\tconst entries = getActiveSessionBranchEntries(source);\n\tconst requestedToolCalls = new Set(\n\t\tentries.flatMap((entry) =>\n\t\t\tentry.type === \"message\" && entry.message.role === \"assistant\"\n\t\t\t\t? entry.message.content.flatMap((part) => (part.type === \"toolCall\" ? [part.id] : []))\n\t\t\t\t: [],\n\t\t),\n\t);\n\tconst answeredToolCalls = new Set(\n\t\tentries.flatMap((entry) =>\n\t\t\tentry.type === \"message\" && entry.message.role === \"toolResult\" ? [entry.message.toolCallId] : [],\n\t\t),\n\t);\n\treturn getLatestHumanInputSnapshots(source)\n\t\t.filter(\n\t\t\t(snapshot) =>\n\t\t\t\tsnapshot.request.source === \"tool\" &&\n\t\t\t\tsnapshot.request.toolCallId !== undefined &&\n\t\t\t\trequestedToolCalls.has(snapshot.request.toolCallId) &&\n\t\t\t\t!answeredToolCalls.has(snapshot.request.toolCallId),\n\t\t)\n\t\t.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0];\n}\n\nfunction preview(value: string): string {\n\tif (value.length <= HUMAN_INPUT_PREVIEW_CHARS) return value;\n\treturn `${value.slice(0, HUMAN_INPUT_PREVIEW_CHARS)}…`;\n}\n\nfunction externalizeAnswer(\n\trequest: HumanInputRequest,\n\tanswer: HumanInputAnswer,\n\tartifactStore: ArtifactStore | undefined,\n): HumanInputAnswer {\n\tif (!answer.custom || Buffer.byteLength(answer.custom, \"utf8\") <= HUMAN_INPUT_INLINE_BYTES || !artifactStore) {\n\t\treturn cloneAnswer(answer);\n\t}\n\tconst record = artifactStore.write({\n\t\tkind: \"transcript_slice\",\n\t\tcontent: answer.custom,\n\t\ttoolName: request.toolName ?? \"human_input\",\n\t\tsessionEntryId: request.requestId,\n\t\tcreatedAtTurn: 0,\n\t\treproducible: false,\n\t});\n\tif (!artifactStore.addReference(record.ref.id, request.requestId)) {\n\t\tthrow new Error(`Failed to retain human-input artifact ${record.ref.id}`);\n\t}\n\treturn {\n\t\t...cloneAnswer(answer),\n\t\tcustom: preview(answer.custom),\n\t\tcustomArtifact: record.ref,\n\t};\n}\n\nexport async function resolveHumanInput(options: ResolveHumanInputOptions): Promise<{\n\tsnapshot: HumanInputSnapshot;\n\timageContents: readonly ImageContent[];\n}> {\n\tconst now = options.now ?? (() => new Date().toISOString());\n\tlet result: HumanInputPresentationResult;\n\tif (options.signal?.aborted) {\n\t\tresult = { answers: [], cancelled: true, reason: \"interrupted\", imageContents: [] };\n\t} else {\n\t\tresult = persistPresentationImages(\n\t\t\tnormalizePresentationResult(\n\t\t\t\toptions.request,\n\t\t\t\tawait options.present(\n\t\t\t\t\t{\n\t\t\t\t\t\trequestId: options.request.requestId,\n\t\t\t\t\t\tquestions: options.request.questions,\n\t\t\t\t\t\tacceptsImages: options.request.acceptsImages,\n\t\t\t\t\t},\n\t\t\t\t\t{ signal: options.signal },\n\t\t\t\t),\n\t\t\t),\n\t\t\toptions.getImageStore?.(),\n\t\t);\n\t}\n\tconst answers = result.answers.map((answer) => externalizeAnswer(options.request, answer, options.artifactStore));\n\tconst snapshot: HumanInputSnapshot = {\n\t\trequest: cloneRequest(options.request),\n\t\tstatus: result.cancelled ? \"cancelled\" : \"answered\",\n\t\tanswers,\n\t\t...(result.reason ? { reason: result.reason } : {}),\n\t\tupdatedAt: now(),\n\t};\n\tappendHumanInputSnapshot(options.sessionManager, snapshot);\n\treturn { snapshot, imageContents: result.cancelled ? [] : result.imageContents };\n}\n\nexport function formatHumanInputAnswerText(snapshot: HumanInputSnapshot): string {\n\tif (snapshot.status === \"cancelled\") {\n\t\treturn snapshot.reason === \"interrupted\"\n\t\t\t? \"User question was interrupted.\"\n\t\t\t: snapshot.reason === \"ui_unavailable\"\n\t\t\t\t? \"User input is unavailable in this host.\"\n\t\t\t\t: \"User cancelled the question without submitting answers.\";\n\t}\n\treturn snapshot.answers\n\t\t.map((answer) => {\n\t\t\tif (answer.skipped) return `${answer.header}: user skipped this question`;\n\t\t\tconst values = [...answer.selected, ...(answer.custom ? [answer.custom] : [])];\n\t\t\tconst artifact = answer.customArtifact\n\t\t\t\t? `\\nFull answer: artifact tool-output:${answer.customArtifact.id} (${answer.customArtifact.byteLength} bytes)`\n\t\t\t\t: \"\";\n\t\t\treturn `${answer.header}: ${values.length > 1 ? \"user selected\" : \"user answered\"}: ${values.join(\", \")}${artifact}`;\n\t\t})\n\t\t.join(\"\\n\");\n}\n"]}

package/dist/core/human-input.js

@@ -0,0 +1,362 @@
+import { randomUUID } from "node:crypto";
+import { getActiveSessionBranchEntries } from "./session-snapshot.js";
+import { isPlainRecord } from "./util/value-guards.js";
+export const HUMAN_INPUT_CUSTOM_TYPE = "human_input_request";
+export const HUMAN_INPUT_WORKER_RESPONSE_CUSTOM_TYPE = "worker-owner-response";
+export const HUMAN_INPUT_INLINE_BYTES = 16 * 1024;
+const HUMAN_INPUT_PREVIEW_CHARS = 4_000;
+function cloneQuestion(question) {
+    return {
+        ...question,
+        options: question.options.map((option) => ({ ...option })),
+    };
+}
+function cloneAnswer(answer) {
+    return {
+        ...answer,
+        selected: [...answer.selected],
+        customArtifact: answer.customArtifact ? { ...answer.customArtifact } : undefined,
+        images: answer.images?.map((image) => ({ ...image })),
+    };
+}
+function cloneRequest(request) {
+    return {
+        ...request,
+        questions: request.questions.map(cloneQuestion),
+    };
+}
+function cloneSnapshot(snapshot) {
+    return {
+        ...snapshot,
+        request: cloneRequest(snapshot.request),
+        answers: snapshot.answers.map(cloneAnswer),
+    };
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isQuestion(value) {
+    if (!isPlainRecord(value) || !Array.isArray(value.options))
+        return false;
+    return (typeof value.id === "string" &&
+        typeof value.header === "string" &&
+        typeof value.question === "string" &&
+        (value.multiSelect === undefined || typeof value.multiSelect === "boolean") &&
+        value.options.every((option) => isPlainRecord(option) && typeof option.label === "string" && typeof option.description === "string"));
+}
+function isArtifactRef(value) {
+    return (isPlainRecord(value) &&
+        typeof value.id === "string" &&
+        typeof value.kind === "string" &&
+        typeof value.byteLength === "number" &&
+        typeof value.createdAtTurn === "number" &&
+        typeof value.reproducible === "boolean");
+}
+function isAnswer(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return (typeof value.id === "string" &&
+        typeof value.header === "string" &&
+        typeof value.question === "string" &&
+        isStringArray(value.selected) &&
+        (value.custom === undefined || typeof value.custom === "string") &&
+        (value.customArtifact === undefined || isArtifactRef(value.customArtifact)) &&
+        (value.images === undefined ||
+            (Array.isArray(value.images) &&
+                value.images.every((image) => isPlainRecord(image) && typeof image.label === "string" && typeof image.mimeType === "string"))) &&
+        typeof value.skipped === "boolean");
+}
+function isImageContent(value) {
+    return (isPlainRecord(value) &&
+        value.type === "image" &&
+        typeof value.data === "string" &&
+        typeof value.mimeType === "string");
+}
+function normalizePresentationResult(request, value) {
+    if (!isPlainRecord(value) || typeof value.cancelled !== "boolean") {
+        throw new Error("Invalid human-input response: expected a typed presentation result");
+    }
+    if (value.cancelled) {
+        const reason = value.reason;
+        if (reason !== undefined &&
+            reason !== "user_cancelled" &&
+            reason !== "ui_unavailable" &&
+            reason !== "interrupted" &&
+            reason !== "invalid_questions") {
+            throw new Error("Invalid human-input response: unknown cancellation reason");
+        }
+        return {
+            answers: [],
+            cancelled: true,
+            ...(reason ? { reason } : {}),
+            imageContents: [],
+        };
+    }
+    if (!Array.isArray(value.answers) || !Array.isArray(value.imageContents)) {
+        throw new Error("Invalid human-input response: answers and imageContents must be arrays");
+    }
+    const answersById = new Map();
+    for (const candidate of value.answers) {
+        if (!isAnswer(candidate))
+            throw new Error("Invalid human-input response: malformed answer");
+        if (candidate.customArtifact !== undefined) {
+            throw new Error("Invalid human-input response: artifact references are harness-owned");
+        }
+        if (answersById.has(candidate.id)) {
+            throw new Error(`Invalid human-input response: duplicate answer '${candidate.id}'`);
+        }
+        answersById.set(candidate.id, candidate);
+    }
+    if (answersById.size !== request.questions.length) {
+        throw new Error("Invalid human-input response: every question must have exactly one answer");
+    }
+    const answers = request.questions.map((question) => {
+        const answer = answersById.get(question.id);
+        if (!answer)
+            throw new Error(`Invalid human-input response: missing answer '${question.id}'`);
+        const optionLabels = new Set(question.options.map((option) => option.label));
+        if (new Set(answer.selected).size !== answer.selected.length) {
+            throw new Error(`Invalid human-input response: duplicate option for '${question.id}'`);
+        }
+        if (answer.selected.some((selection) => !optionLabels.has(selection))) {
+            throw new Error(`Invalid human-input response: unknown option for '${question.id}'`);
+        }
+        if (!question.multiSelect && answer.selected.length > 1) {
+            throw new Error(`Invalid human-input response: '${question.id}' is single-select`);
+        }
+        if (answer.skipped &&
+            (answer.selected.length > 0 || Boolean(answer.custom) || (answer.images?.length ?? 0) > 0)) {
+            throw new Error(`Invalid human-input response: skipped answer '${question.id}' contains a value`);
+        }
+        return {
+            ...cloneAnswer(answer),
+            header: question.header,
+            question: question.question,
+        };
+    });
+    if (!value.imageContents.every(isImageContent)) {
+        throw new Error("Invalid human-input response: malformed image content");
+    }
+    const answerImages = answers.flatMap((answer) => answer.images ?? []);
+    if (answerImages.length !== value.imageContents.length) {
+        throw new Error("Invalid human-input response: image metadata does not match image content");
+    }
+    if (!request.acceptsImages && value.imageContents.length > 0) {
+        throw new Error("Invalid human-input response: the selected model does not accept images");
+    }
+    for (let index = 0; index < answerImages.length; index++) {
+        if (answerImages[index]?.mimeType !== value.imageContents[index]?.mimeType) {
+            throw new Error("Invalid human-input response: image MIME metadata does not match image content");
+        }
+    }
+    return {
+        answers,
+        cancelled: false,
+        imageContents: value.imageContents.map((image) => ({ ...image })),
+    };
+}
+function persistPresentationImages(result, imageStore) {
+    if (!imageStore || result.cancelled || result.imageContents.length === 0)
+        return result;
+    let imageIndex = 0;
+    const durableContents = [];
+    const answers = result.answers.map((answer) => {
+        let custom = answer.custom;
+        const images = answer.images?.map((image) => {
+            const content = result.imageContents[imageIndex++];
+            if (!content)
+                throw new Error("Human-input image metadata exceeds supplied image content");
+            const sequenceMatch = /^\[Image #(\d{1,6})\]$/iu.exec(image.label);
+            const stored = imageStore.retainContent(content, sequenceMatch ? Number(sequenceMatch[1]) : undefined);
+            const durableLabel = `[Image #${stored.sequence}]`;
+            if (custom?.includes(image.label))
+                custom = custom.split(image.label).join(durableLabel);
+            durableContents.push({
+                type: "image",
+                data: Buffer.from(stored.bytes).toString("base64"),
+                mimeType: stored.mimeType,
+            });
+            return { label: durableLabel, mimeType: stored.mimeType };
+        });
+        return {
+            ...cloneAnswer(answer),
+            ...(custom !== undefined ? { custom } : {}),
+            ...(images && images.length > 0 ? { images } : {}),
+        };
+    });
+    return { ...result, answers, imageContents: durableContents };
+}
+function isRequest(value) {
+    if (!isPlainRecord(value) || !Array.isArray(value.questions))
+        return false;
+    return (typeof value.requestId === "string" &&
+        (value.source === "tool" || value.source === "worker") &&
+        (value.toolCallId === undefined || typeof value.toolCallId === "string") &&
+        (value.toolName === undefined || typeof value.toolName === "string") &&
+        (value.workerRequestId === undefined || typeof value.workerRequestId === "string") &&
+        value.questions.every(isQuestion) &&
+        typeof value.acceptsImages === "boolean" &&
+        typeof value.createdAt === "string");
+}
+function decodeSnapshot(data) {
+    if (!isPlainRecord(data) || data.version !== 1 || !isPlainRecord(data.snapshot))
+        return undefined;
+    const snapshot = data.snapshot;
+    if (!isRequest(snapshot.request) ||
+        (snapshot.status !== "pending" && snapshot.status !== "answered" && snapshot.status !== "cancelled") ||
+        !Array.isArray(snapshot.answers) ||
+        !snapshot.answers.every(isAnswer) ||
+        (snapshot.reason !== undefined &&
+            snapshot.reason !== "user_cancelled" &&
+            snapshot.reason !== "ui_unavailable" &&
+            snapshot.reason !== "interrupted" &&
+            snapshot.reason !== "invalid_questions") ||
+        typeof snapshot.updatedAt !== "string") {
+        return undefined;
+    }
+    return cloneSnapshot(snapshot);
+}
+export function createHumanInputRequest(options) {
+    const now = options.now?.() ?? new Date().toISOString();
+    return {
+        requestId: `human-input:${options.toolCallId ?? options.workerRequestId ?? randomUUID()}`,
+        source: options.source,
+        ...(options.toolCallId ? { toolCallId: options.toolCallId } : {}),
+        ...(options.toolName ? { toolName: options.toolName } : {}),
+        ...(options.workerRequestId ? { workerRequestId: options.workerRequestId } : {}),
+        questions: options.questions.map(cloneQuestion),
+        acceptsImages: options.acceptsImages,
+        createdAt: now,
+    };
+}
+export function appendHumanInputSnapshot(sessionManager, snapshot) {
+    const payload = { version: 1, snapshot: cloneSnapshot(snapshot) };
+    return sessionManager.appendCustomEntry(HUMAN_INPUT_CUSTOM_TYPE, payload);
+}
+export function beginHumanInputRequest(sessionManager, request) {
+    const snapshot = {
+        request: cloneRequest(request),
+        status: "pending",
+        answers: [],
+        updatedAt: request.createdAt,
+    };
+    appendHumanInputSnapshot(sessionManager, snapshot);
+    return snapshot;
+}
+export function getHumanInputSnapshots(entries) {
+    const snapshots = [];
+    for (const entry of entries) {
+        if (entry.type !== "custom" || entry.customType !== HUMAN_INPUT_CUSTOM_TYPE)
+            continue;
+        const snapshot = decodeSnapshot(entry.data);
+        if (snapshot)
+            snapshots.push(snapshot);
+    }
+    return snapshots;
+}
+export function getLatestHumanInputSnapshots(source) {
+    const latest = new Map();
+    for (const snapshot of getHumanInputSnapshots(getActiveSessionBranchEntries(source))) {
+        latest.set(snapshot.request.requestId, snapshot);
+    }
+    return [...latest.values()];
+}
+export function getWorkerHumanInputsRequiringDelivery(source) {
+    const entries = getActiveSessionBranchEntries(source);
+    const deliveredRequestIds = new Set(entries.flatMap((entry) => {
+        if (entry.type !== "custom_message" ||
+            entry.customType !== HUMAN_INPUT_WORKER_RESPONSE_CUSTOM_TYPE ||
+            !isPlainRecord(entry.details) ||
+            typeof entry.details.requestId !== "string") {
+            return [];
+        }
+        return [entry.details.requestId];
+    }));
+    return getLatestHumanInputSnapshots(source)
+        .filter((snapshot) => snapshot.request.source === "worker" && !deliveredRequestIds.has(snapshot.request.requestId))
+        .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
+}
+export function getResumableHumanInputSnapshot(source) {
+    const entries = getActiveSessionBranchEntries(source);
+    const requestedToolCalls = new Set(entries.flatMap((entry) => entry.type === "message" && entry.message.role === "assistant"
+        ? entry.message.content.flatMap((part) => (part.type === "toolCall" ? [part.id] : []))
+        : []));
+    const answeredToolCalls = new Set(entries.flatMap((entry) => entry.type === "message" && entry.message.role === "toolResult" ? [entry.message.toolCallId] : []));
+    return getLatestHumanInputSnapshots(source)
+        .filter((snapshot) => snapshot.request.source === "tool" &&
+        snapshot.request.toolCallId !== undefined &&
+        requestedToolCalls.has(snapshot.request.toolCallId) &&
+        !answeredToolCalls.has(snapshot.request.toolCallId))
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0];
+}
+function preview(value) {
+    if (value.length <= HUMAN_INPUT_PREVIEW_CHARS)
+        return value;
+    return `${value.slice(0, HUMAN_INPUT_PREVIEW_CHARS)}…`;
+}
+function externalizeAnswer(request, answer, artifactStore) {
+    if (!answer.custom || Buffer.byteLength(answer.custom, "utf8") <= HUMAN_INPUT_INLINE_BYTES || !artifactStore) {
+        return cloneAnswer(answer);
+    }
+    const record = artifactStore.write({
+        kind: "transcript_slice",
+        content: answer.custom,
+        toolName: request.toolName ?? "human_input",
+        sessionEntryId: request.requestId,
+        createdAtTurn: 0,
+        reproducible: false,
+    });
+    if (!artifactStore.addReference(record.ref.id, request.requestId)) {
+        throw new Error(`Failed to retain human-input artifact ${record.ref.id}`);
+    }
+    return {
+        ...cloneAnswer(answer),
+        custom: preview(answer.custom),
+        customArtifact: record.ref,
+    };
+}
+export async function resolveHumanInput(options) {
+    const now = options.now ?? (() => new Date().toISOString());
+    let result;
+    if (options.signal?.aborted) {
+        result = { answers: [], cancelled: true, reason: "interrupted", imageContents: [] };
+    }
+    else {
+        result = persistPresentationImages(normalizePresentationResult(options.request, await options.present({
+            requestId: options.request.requestId,
+            questions: options.request.questions,
+            acceptsImages: options.request.acceptsImages,
+        }, { signal: options.signal })), options.getImageStore?.());
+    }
+    const answers = result.answers.map((answer) => externalizeAnswer(options.request, answer, options.artifactStore));
+    const snapshot = {
+        request: cloneRequest(options.request),
+        status: result.cancelled ? "cancelled" : "answered",
+        answers,
+        ...(result.reason ? { reason: result.reason } : {}),
+        updatedAt: now(),
+    };
+    appendHumanInputSnapshot(options.sessionManager, snapshot);
+    return { snapshot, imageContents: result.cancelled ? [] : result.imageContents };
+}
+export function formatHumanInputAnswerText(snapshot) {
+    if (snapshot.status === "cancelled") {
+        return snapshot.reason === "interrupted"
+            ? "User question was interrupted."
+            : snapshot.reason === "ui_unavailable"
+                ? "User input is unavailable in this host."
+                : "User cancelled the question without submitting answers.";
+    }
+    return snapshot.answers
+        .map((answer) => {
+        if (answer.skipped)
+            return `${answer.header}: user skipped this question`;
+        const values = [...answer.selected, ...(answer.custom ? [answer.custom] : [])];
+        const artifact = answer.customArtifact
+            ? `\nFull answer: artifact tool-output:${answer.customArtifact.id} (${answer.customArtifact.byteLength} bytes)`
+            : "";
+        return `${answer.header}: ${values.length > 1 ? "user selected" : "user answered"}: ${values.join(", ")}${artifact}`;
+    })
+        .join("\n");
+}
+//# sourceMappingURL=human-input.js.map

package/dist/core/human-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-input.js","sourceRoot":"","sources":["../../src/core/human-input.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport type { SessionEntry, SessionManager } from \"@caupulican/pi-agent-core/node\";\nimport type { ImageContent } from \"@caupulican/pi-ai\";\nimport type { ArtifactStore } from \"./context/context-artifacts.ts\";\nimport type { ContextArtifactRef } from \"./context/context-item.ts\";\nimport type { SessionImageStore } from \"./session-image-store.ts\";\nimport { getActiveSessionBranchEntries, type SessionBranchEntrySource } from \"./session-snapshot.ts\";\nimport { isPlainRecord } from \"./util/value-guards.ts\";\n\nexport const HUMAN_INPUT_CUSTOM_TYPE = \"human_input_request\";\nexport const HUMAN_INPUT_WORKER_RESPONSE_CUSTOM_TYPE = \"worker-owner-response\";\nexport const HUMAN_INPUT_INLINE_BYTES = 16 * 1024;\nconst HUMAN_INPUT_PREVIEW_CHARS = 4_000;\n\nexport interface HumanInputOption {\n\tlabel: string;\n\tdescription: string;\n}\n\nexport interface HumanInputQuestion {\n\tid: string;\n\theader: string;\n\tquestion: string;\n\toptions: readonly HumanInputOption[];\n\tmultiSelect?: boolean;\n}\n\nexport interface HumanInputAnswerImage {\n\tlabel: string;\n\tmimeType: string;\n}\n\nexport interface HumanInputAnswer {\n\tid: string;\n\theader: string;\n\tquestion: string;\n\tselected: readonly string[];\n\t/** Inline answer, or a bounded preview when customArtifact is present. */\n\tcustom?: string;\n\t/** Exact full answer retained out of prompt context when it exceeds the inline bound. */\n\tcustomArtifact?: ContextArtifactRef;\n\timages?: readonly HumanInputAnswerImage[];\n\tskipped: boolean;\n}\n\nexport type HumanInputStopReason = \"user_cancelled\" | \"ui_unavailable\" | \"interrupted\" | \"invalid_questions\";\n\nexport interface HumanInputPresentationRequest {\n\trequestId: string;\n\tquestions: readonly HumanInputQuestion[];\n\tacceptsImages: boolean;\n}\n\nexport interface HumanInputPresentationResult {\n\tanswers: readonly HumanInputAnswer[];\n\tcancelled: boolean;\n\treason?: HumanInputStopReason;\n\timageContents: readonly ImageContent[];\n}\n\nexport type HumanInputSource = \"tool\" | \"worker\";\n\nexport interface HumanInputRequest {\n\trequestId: string;\n\tsource: HumanInputSource;\n\ttoolCallId?: string;\n\ttoolName?: string;\n\tworkerRequestId?: string;\n\tquestions: readonly HumanInputQuestion[];\n\tacceptsImages: boolean;\n\tcreatedAt: string;\n}\n\nexport type HumanInputStatus = \"pending\" | \"answered\" | \"cancelled\";\n\nexport interface HumanInputSnapshot {\n\trequest: HumanInputRequest;\n\tstatus: HumanInputStatus;\n\tanswers: readonly HumanInputAnswer[];\n\treason?: HumanInputStopReason;\n\tupdatedAt: string;\n}\n\ninterface HumanInputSnapshotPayload {\n\tversion: 1;\n\tsnapshot: HumanInputSnapshot;\n}\n\nexport interface HumanInputRequestOptions {\n\tsource: HumanInputSource;\n\ttoolCallId?: string;\n\ttoolName?: string;\n\tworkerRequestId?: string;\n\tquestions: readonly HumanInputQuestion[];\n\tacceptsImages: boolean;\n\tnow?: () => string;\n}\n\nexport interface ResolveHumanInputOptions {\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">;\n\trequest: HumanInputRequest;\n\tpresent: (\n\t\trequest: HumanInputPresentationRequest,\n\t\toptions?: { signal?: AbortSignal },\n\t) => Promise<HumanInputPresentationResult>;\n\tartifactStore?: ArtifactStore;\n\tgetImageStore?: () => Pick<SessionImageStore, \"retainContent\"> | undefined;\n\tsignal?: AbortSignal;\n\tnow?: () => string;\n}\n\nfunction cloneQuestion(question: HumanInputQuestion): HumanInputQuestion {\n\treturn {\n\t\t...question,\n\t\toptions: question.options.map((option) => ({ ...option })),\n\t};\n}\n\nfunction cloneAnswer(answer: HumanInputAnswer): HumanInputAnswer {\n\treturn {\n\t\t...answer,\n\t\tselected: [...answer.selected],\n\t\tcustomArtifact: answer.customArtifact ? { ...answer.customArtifact } : undefined,\n\t\timages: answer.images?.map((image) => ({ ...image })),\n\t};\n}\n\nfunction cloneRequest(request: HumanInputRequest): HumanInputRequest {\n\treturn {\n\t\t...request,\n\t\tquestions: request.questions.map(cloneQuestion),\n\t};\n}\n\nfunction cloneSnapshot(snapshot: HumanInputSnapshot): HumanInputSnapshot {\n\treturn {\n\t\t...snapshot,\n\t\trequest: cloneRequest(snapshot.request),\n\t\tanswers: snapshot.answers.map(cloneAnswer),\n\t};\n}\n\nfunction isStringArray(value: unknown): value is string[] {\n\treturn Array.isArray(value) && value.every((entry) => typeof entry === \"string\");\n}\n\nfunction isQuestion(value: unknown): value is HumanInputQuestion {\n\tif (!isPlainRecord(value) || !Array.isArray(value.options)) return false;\n\treturn (\n\t\ttypeof value.id === \"string\" &&\n\t\ttypeof value.header === \"string\" &&\n\t\ttypeof value.question === \"string\" &&\n\t\t(value.multiSelect === undefined || typeof value.multiSelect === \"boolean\") &&\n\t\tvalue.options.every(\n\t\t\t(option) =>\n\t\t\t\tisPlainRecord(option) && typeof option.label === \"string\" && typeof option.description === \"string\",\n\t\t)\n\t);\n}\n\nfunction isArtifactRef(value: unknown): value is ContextArtifactRef {\n\treturn (\n\t\tisPlainRecord(value) &&\n\t\ttypeof value.id === \"string\" &&\n\t\ttypeof value.kind === \"string\" &&\n\t\ttypeof value.byteLength === \"number\" &&\n\t\ttypeof value.createdAtTurn === \"number\" &&\n\t\ttypeof value.reproducible === \"boolean\"\n\t);\n}\n\nfunction isAnswer(value: unknown): value is HumanInputAnswer {\n\tif (!isPlainRecord(value)) return false;\n\treturn (\n\t\ttypeof value.id === \"string\" &&\n\t\ttypeof value.header === \"string\" &&\n\t\ttypeof value.question === \"string\" &&\n\t\tisStringArray(value.selected) &&\n\t\t(value.custom === undefined || typeof value.custom === \"string\") &&\n\t\t(value.customArtifact === undefined || isArtifactRef(value.customArtifact)) &&\n\t\t(value.images === undefined ||\n\t\t\t(Array.isArray(value.images) &&\n\t\t\t\tvalue.images.every(\n\t\t\t\t\t(image) => isPlainRecord(image) && typeof image.label === \"string\" && typeof image.mimeType === \"string\",\n\t\t\t\t))) &&\n\t\ttypeof value.skipped === \"boolean\"\n\t);\n}\n\nfunction isImageContent(value: unknown): value is ImageContent {\n\treturn (\n\t\tisPlainRecord(value) &&\n\t\tvalue.type === \"image\" &&\n\t\ttypeof value.data === \"string\" &&\n\t\ttypeof value.mimeType === \"string\"\n\t);\n}\n\nfunction normalizePresentationResult(request: HumanInputRequest, value: unknown): HumanInputPresentationResult {\n\tif (!isPlainRecord(value) || typeof value.cancelled !== \"boolean\") {\n\t\tthrow new Error(\"Invalid human-input response: expected a typed presentation result\");\n\t}\n\tif (value.cancelled) {\n\t\tconst reason = value.reason;\n\t\tif (\n\t\t\treason !== undefined &&\n\t\t\treason !== \"user_cancelled\" &&\n\t\t\treason !== \"ui_unavailable\" &&\n\t\t\treason !== \"interrupted\" &&\n\t\t\treason !== \"invalid_questions\"\n\t\t) {\n\t\t\tthrow new Error(\"Invalid human-input response: unknown cancellation reason\");\n\t\t}\n\t\treturn {\n\t\t\tanswers: [],\n\t\t\tcancelled: true,\n\t\t\t...(reason ? { reason } : {}),\n\t\t\timageContents: [],\n\t\t};\n\t}\n\tif (!Array.isArray(value.answers) || !Array.isArray(value.imageContents)) {\n\t\tthrow new Error(\"Invalid human-input response: answers and imageContents must be arrays\");\n\t}\n\tconst answersById = new Map<string, HumanInputAnswer>();\n\tfor (const candidate of value.answers) {\n\t\tif (!isAnswer(candidate)) throw new Error(\"Invalid human-input response: malformed answer\");\n\t\tif (candidate.customArtifact !== undefined) {\n\t\t\tthrow new Error(\"Invalid human-input response: artifact references are harness-owned\");\n\t\t}\n\t\tif (answersById.has(candidate.id)) {\n\t\t\tthrow new Error(`Invalid human-input response: duplicate answer '${candidate.id}'`);\n\t\t}\n\t\tanswersById.set(candidate.id, candidate);\n\t}\n\tif (answersById.size !== request.questions.length) {\n\t\tthrow new Error(\"Invalid human-input response: every question must have exactly one answer\");\n\t}\n\n\tconst answers = request.questions.map((question) => {\n\t\tconst answer = answersById.get(question.id);\n\t\tif (!answer) throw new Error(`Invalid human-input response: missing answer '${question.id}'`);\n\t\tconst optionLabels = new Set(question.options.map((option) => option.label));\n\t\tif (new Set(answer.selected).size !== answer.selected.length) {\n\t\t\tthrow new Error(`Invalid human-input response: duplicate option for '${question.id}'`);\n\t\t}\n\t\tif (answer.selected.some((selection) => !optionLabels.has(selection))) {\n\t\t\tthrow new Error(`Invalid human-input response: unknown option for '${question.id}'`);\n\t\t}\n\t\tif (!question.multiSelect && answer.selected.length > 1) {\n\t\t\tthrow new Error(`Invalid human-input response: '${question.id}' is single-select`);\n\t\t}\n\t\tif (\n\t\t\tanswer.skipped &&\n\t\t\t(answer.selected.length > 0 || Boolean(answer.custom) || (answer.images?.length ?? 0) > 0)\n\t\t) {\n\t\t\tthrow new Error(`Invalid human-input response: skipped answer '${question.id}' contains a value`);\n\t\t}\n\t\treturn {\n\t\t\t...cloneAnswer(answer),\n\t\t\theader: question.header,\n\t\t\tquestion: question.question,\n\t\t};\n\t});\n\tif (!value.imageContents.every(isImageContent)) {\n\t\tthrow new Error(\"Invalid human-input response: malformed image content\");\n\t}\n\tconst answerImages = answers.flatMap((answer) => answer.images ?? []);\n\tif (answerImages.length !== value.imageContents.length) {\n\t\tthrow new Error(\"Invalid human-input response: image metadata does not match image content\");\n\t}\n\tif (!request.acceptsImages && value.imageContents.length > 0) {\n\t\tthrow new Error(\"Invalid human-input response: the selected model does not accept images\");\n\t}\n\tfor (let index = 0; index < answerImages.length; index++) {\n\t\tif (answerImages[index]?.mimeType !== value.imageContents[index]?.mimeType) {\n\t\t\tthrow new Error(\"Invalid human-input response: image MIME metadata does not match image content\");\n\t\t}\n\t}\n\treturn {\n\t\tanswers,\n\t\tcancelled: false,\n\t\timageContents: value.imageContents.map((image) => ({ ...image })),\n\t};\n}\n\nfunction persistPresentationImages(\n\tresult: HumanInputPresentationResult,\n\timageStore: Pick<SessionImageStore, \"retainContent\"> | undefined,\n): HumanInputPresentationResult {\n\tif (!imageStore || result.cancelled || result.imageContents.length === 0) return result;\n\tlet imageIndex = 0;\n\tconst durableContents: ImageContent[] = [];\n\tconst answers = result.answers.map((answer) => {\n\t\tlet custom = answer.custom;\n\t\tconst images = answer.images?.map((image) => {\n\t\t\tconst content = result.imageContents[imageIndex++];\n\t\t\tif (!content) throw new Error(\"Human-input image metadata exceeds supplied image content\");\n\t\t\tconst sequenceMatch = /^\\[Image #(\\d{1,6})\\]$/iu.exec(image.label);\n\t\t\tconst stored = imageStore.retainContent(content, sequenceMatch ? Number(sequenceMatch[1]) : undefined);\n\t\t\tconst durableLabel = `[Image #${stored.sequence}]`;\n\t\t\tif (custom?.includes(image.label)) custom = custom.split(image.label).join(durableLabel);\n\t\t\tdurableContents.push({\n\t\t\t\ttype: \"image\",\n\t\t\t\tdata: Buffer.from(stored.bytes).toString(\"base64\"),\n\t\t\t\tmimeType: stored.mimeType,\n\t\t\t});\n\t\t\treturn { label: durableLabel, mimeType: stored.mimeType };\n\t\t});\n\t\treturn {\n\t\t\t...cloneAnswer(answer),\n\t\t\t...(custom !== undefined ? { custom } : {}),\n\t\t\t...(images && images.length > 0 ? { images } : {}),\n\t\t};\n\t});\n\treturn { ...result, answers, imageContents: durableContents };\n}\n\nfunction isRequest(value: unknown): value is HumanInputRequest {\n\tif (!isPlainRecord(value) || !Array.isArray(value.questions)) return false;\n\treturn (\n\t\ttypeof value.requestId === \"string\" &&\n\t\t(value.source === \"tool\" || value.source === \"worker\") &&\n\t\t(value.toolCallId === undefined || typeof value.toolCallId === \"string\") &&\n\t\t(value.toolName === undefined || typeof value.toolName === \"string\") &&\n\t\t(value.workerRequestId === undefined || typeof value.workerRequestId === \"string\") &&\n\t\tvalue.questions.every(isQuestion) &&\n\t\ttypeof value.acceptsImages === \"boolean\" &&\n\t\ttypeof value.createdAt === \"string\"\n\t);\n}\n\nfunction decodeSnapshot(data: unknown): HumanInputSnapshot | undefined {\n\tif (!isPlainRecord(data) || data.version !== 1 || !isPlainRecord(data.snapshot)) return undefined;\n\tconst snapshot = data.snapshot;\n\tif (\n\t\t!isRequest(snapshot.request) ||\n\t\t(snapshot.status !== \"pending\" && snapshot.status !== \"answered\" && snapshot.status !== \"cancelled\") ||\n\t\t!Array.isArray(snapshot.answers) ||\n\t\t!snapshot.answers.every(isAnswer) ||\n\t\t(snapshot.reason !== undefined &&\n\t\t\tsnapshot.reason !== \"user_cancelled\" &&\n\t\t\tsnapshot.reason !== \"ui_unavailable\" &&\n\t\t\tsnapshot.reason !== \"interrupted\" &&\n\t\t\tsnapshot.reason !== \"invalid_questions\") ||\n\t\ttypeof snapshot.updatedAt !== \"string\"\n\t) {\n\t\treturn undefined;\n\t}\n\treturn cloneSnapshot(snapshot as unknown as HumanInputSnapshot);\n}\n\nexport function createHumanInputRequest(options: HumanInputRequestOptions): HumanInputRequest {\n\tconst now = options.now?.() ?? new Date().toISOString();\n\treturn {\n\t\trequestId: `human-input:${options.toolCallId ?? options.workerRequestId ?? randomUUID()}`,\n\t\tsource: options.source,\n\t\t...(options.toolCallId ? { toolCallId: options.toolCallId } : {}),\n\t\t...(options.toolName ? { toolName: options.toolName } : {}),\n\t\t...(options.workerRequestId ? { workerRequestId: options.workerRequestId } : {}),\n\t\tquestions: options.questions.map(cloneQuestion),\n\t\tacceptsImages: options.acceptsImages,\n\t\tcreatedAt: now,\n\t};\n}\n\nexport function appendHumanInputSnapshot(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\tsnapshot: HumanInputSnapshot,\n): string {\n\tconst payload: HumanInputSnapshotPayload = { version: 1, snapshot: cloneSnapshot(snapshot) };\n\treturn sessionManager.appendCustomEntry(HUMAN_INPUT_CUSTOM_TYPE, payload);\n}\n\nexport function beginHumanInputRequest(\n\tsessionManager: Pick<SessionManager, \"appendCustomEntry\">,\n\trequest: HumanInputRequest,\n): HumanInputSnapshot {\n\tconst snapshot: HumanInputSnapshot = {\n\t\trequest: cloneRequest(request),\n\t\tstatus: \"pending\",\n\t\tanswers: [],\n\t\tupdatedAt: request.createdAt,\n\t};\n\tappendHumanInputSnapshot(sessionManager, snapshot);\n\treturn snapshot;\n}\n\nexport function getHumanInputSnapshots(entries: readonly SessionEntry[]): HumanInputSnapshot[] {\n\tconst snapshots: HumanInputSnapshot[] = [];\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"custom\" || entry.customType !== HUMAN_INPUT_CUSTOM_TYPE) continue;\n\t\tconst snapshot = decodeSnapshot(entry.data);\n\t\tif (snapshot) snapshots.push(snapshot);\n\t}\n\treturn snapshots;\n}\n\nexport function getLatestHumanInputSnapshots(source: SessionBranchEntrySource): HumanInputSnapshot[] {\n\tconst latest = new Map<string, HumanInputSnapshot>();\n\tfor (const snapshot of getHumanInputSnapshots(getActiveSessionBranchEntries(source))) {\n\t\tlatest.set(snapshot.request.requestId, snapshot);\n\t}\n\treturn [...latest.values()];\n}\n\nexport function getWorkerHumanInputsRequiringDelivery(source: SessionBranchEntrySource): HumanInputSnapshot[] {\n\tconst entries = getActiveSessionBranchEntries(source);\n\tconst deliveredRequestIds = new Set(\n\t\tentries.flatMap((entry) => {\n\t\t\tif (\n\t\t\t\tentry.type !== \"custom_message\" ||\n\t\t\t\tentry.customType !== HUMAN_INPUT_WORKER_RESPONSE_CUSTOM_TYPE ||\n\t\t\t\t!isPlainRecord(entry.details) ||\n\t\t\t\ttypeof entry.details.requestId !== \"string\"\n\t\t\t) {\n\t\t\t\treturn [];\n\t\t\t}\n\t\t\treturn [entry.details.requestId];\n\t\t}),\n\t);\n\treturn getLatestHumanInputSnapshots(source)\n\t\t.filter(\n\t\t\t(snapshot) => snapshot.request.source === \"worker\" && !deliveredRequestIds.has(snapshot.request.requestId),\n\t\t)\n\t\t.sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));\n}\n\nexport function getResumableHumanInputSnapshot(source: SessionBranchEntrySource): HumanInputSnapshot | undefined {\n\tconst entries = getActiveSessionBranchEntries(source);\n\tconst requestedToolCalls = new Set(\n\t\tentries.flatMap((entry) =>\n\t\t\tentry.type === \"message\" && entry.message.role === \"assistant\"\n\t\t\t\t? entry.message.content.flatMap((part) => (part.type === \"toolCall\" ? [part.id] : []))\n\t\t\t\t: [],\n\t\t),\n\t);\n\tconst answeredToolCalls = new Set(\n\t\tentries.flatMap((entry) =>\n\t\t\tentry.type === \"message\" && entry.message.role === \"toolResult\" ? [entry.message.toolCallId] : [],\n\t\t),\n\t);\n\treturn getLatestHumanInputSnapshots(source)\n\t\t.filter(\n\t\t\t(snapshot) =>\n\t\t\t\tsnapshot.request.source === \"tool\" &&\n\t\t\t\tsnapshot.request.toolCallId !== undefined &&\n\t\t\t\trequestedToolCalls.has(snapshot.request.toolCallId) &&\n\t\t\t\t!answeredToolCalls.has(snapshot.request.toolCallId),\n\t\t)\n\t\t.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0];\n}\n\nfunction preview(value: string): string {\n\tif (value.length <= HUMAN_INPUT_PREVIEW_CHARS) return value;\n\treturn `${value.slice(0, HUMAN_INPUT_PREVIEW_CHARS)}…`;\n}\n\nfunction externalizeAnswer(\n\trequest: HumanInputRequest,\n\tanswer: HumanInputAnswer,\n\tartifactStore: ArtifactStore | undefined,\n): HumanInputAnswer {\n\tif (!answer.custom || Buffer.byteLength(answer.custom, \"utf8\") <= HUMAN_INPUT_INLINE_BYTES || !artifactStore) {\n\t\treturn cloneAnswer(answer);\n\t}\n\tconst record = artifactStore.write({\n\t\tkind: \"transcript_slice\",\n\t\tcontent: answer.custom,\n\t\ttoolName: request.toolName ?? \"human_input\",\n\t\tsessionEntryId: request.requestId,\n\t\tcreatedAtTurn: 0,\n\t\treproducible: false,\n\t});\n\tif (!artifactStore.addReference(record.ref.id, request.requestId)) {\n\t\tthrow new Error(`Failed to retain human-input artifact ${record.ref.id}`);\n\t}\n\treturn {\n\t\t...cloneAnswer(answer),\n\t\tcustom: preview(answer.custom),\n\t\tcustomArtifact: record.ref,\n\t};\n}\n\nexport async function resolveHumanInput(options: ResolveHumanInputOptions): Promise<{\n\tsnapshot: HumanInputSnapshot;\n\timageContents: readonly ImageContent[];\n}> {\n\tconst now = options.now ?? (() => new Date().toISOString());\n\tlet result: HumanInputPresentationResult;\n\tif (options.signal?.aborted) {\n\t\tresult = { answers: [], cancelled: true, reason: \"interrupted\", imageContents: [] };\n\t} else {\n\t\tresult = persistPresentationImages(\n\t\t\tnormalizePresentationResult(\n\t\t\t\toptions.request,\n\t\t\t\tawait options.present(\n\t\t\t\t\t{\n\t\t\t\t\t\trequestId: options.request.requestId,\n\t\t\t\t\t\tquestions: options.request.questions,\n\t\t\t\t\t\tacceptsImages: options.request.acceptsImages,\n\t\t\t\t\t},\n\t\t\t\t\t{ signal: options.signal },\n\t\t\t\t),\n\t\t\t),\n\t\t\toptions.getImageStore?.(),\n\t\t);\n\t}\n\tconst answers = result.answers.map((answer) => externalizeAnswer(options.request, answer, options.artifactStore));\n\tconst snapshot: HumanInputSnapshot = {\n\t\trequest: cloneRequest(options.request),\n\t\tstatus: result.cancelled ? \"cancelled\" : \"answered\",\n\t\tanswers,\n\t\t...(result.reason ? { reason: result.reason } : {}),\n\t\tupdatedAt: now(),\n\t};\n\tappendHumanInputSnapshot(options.sessionManager, snapshot);\n\treturn { snapshot, imageContents: result.cancelled ? [] : result.imageContents };\n}\n\nexport function formatHumanInputAnswerText(snapshot: HumanInputSnapshot): string {\n\tif (snapshot.status === \"cancelled\") {\n\t\treturn snapshot.reason === \"interrupted\"\n\t\t\t? \"User question was interrupted.\"\n\t\t\t: snapshot.reason === \"ui_unavailable\"\n\t\t\t\t? \"User input is unavailable in this host.\"\n\t\t\t\t: \"User cancelled the question without submitting answers.\";\n\t}\n\treturn snapshot.answers\n\t\t.map((answer) => {\n\t\t\tif (answer.skipped) return `${answer.header}: user skipped this question`;\n\t\t\tconst values = [...answer.selected, ...(answer.custom ? [answer.custom] : [])];\n\t\t\tconst artifact = answer.customArtifact\n\t\t\t\t? `\\nFull answer: artifact tool-output:${answer.customArtifact.id} (${answer.customArtifact.byteLength} bytes)`\n\t\t\t\t: \"\";\n\t\t\treturn `${answer.header}: ${values.length > 1 ? \"user selected\" : \"user answered\"}: ${values.join(\", \")}${artifact}`;\n\t\t})\n\t\t.join(\"\\n\");\n}\n"]}

package/dist/core/index.d.ts

@@ -3,10 +3,18 @@
  */
 export type { CompactionResult } from "@caupulican/pi-agent-core/node";
 export { AgentSession, type AgentSessionConfig, type AgentSessionEvent, type AgentSessionEventListener, type ModelCycleResult, type PromptOptions, type SessionStats, } from "./agent-session.ts";
-export { AgentSessionRuntime, type CreateAgentSessionRuntimeFactory, type CreateAgentSessionRuntimeResult, createAgentSessionRuntime, } from "./agent-session-runtime.ts";
+export { AgentSessionRuntime, type AgentSessionRuntimeResource, type AgentSessionSwitchOptions, type CreateAgentSessionRuntimeFactory, type CreateAgentSessionRuntimeResult, createAgentSessionRuntime, SessionReplacementCallbackError, SessionReplacementRuntimeError, } from "./agent-session-runtime.ts";
 export { type AgentSessionRuntimeDiagnostic, type AgentSessionServices, type CreateAgentSessionFromServicesOptions, type CreateAgentSessionServicesOptions, createAgentSessionFromServices, createAgentSessionServices, } from "./agent-session-services.ts";
 export { type BashExecutorOptions, type BashResult, executeBashWithOperations } from "./bash-executor.ts";
 export { createEventBus, type EventBus, type EventBusController } from "./event-bus.ts";
 export { type AgentEndEvent, type AgentStartEvent, type AgentToolResult, type AgentToolUpdateCallback, type BeforeAgentStartEvent, type BeforeAgentStartEventResult, type BuildSystemPromptOptions, type ContextEvent, defineTool, discoverAndLoadExtensions, type ExecOptions, type ExecResult, type Extension, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, type ExtensionError, type ExtensionEvent, type ExtensionFactory, type ExtensionFlag, type ExtensionHandler, ExtensionRunner, type ExtensionShortcut, type ExtensionUIContext, type LoadExtensionsResult, type MessageRenderer, type RegisteredCommand, type SessionBeforeCompactEvent, type SessionBeforeForkEvent, type SessionBeforeSwitchEvent, type SessionBeforeTreeEvent, type SessionCompactEvent, type SessionShutdownEvent, type SessionStartEvent, type SessionTreeEvent, type ToolCallEvent, type ToolCallEventResult, type ToolDefinition, type ToolRenderResultOptions, type ToolResultEvent, type TurnEndEvent, type TurnStartEvent, type WorkingIndicatorOptions, } from "./extensions/index.ts";
+export * from "./orchestration/capability-gateway.ts";
+export * from "./orchestration/contracts.ts";
+export * from "./orchestration/event-store.ts";
+export * from "./orchestration/model-binding.ts";
+export * from "./orchestration/policy-compiler.ts";
+export * from "./orchestration/profile-registry.ts";
+export * from "./orchestration/profile-store.ts";
+export * from "./orchestration/task-runtime.ts";
 export { createSyntheticSourceInfo } from "./source-info.ts";
 //# sourceMappingURL=index.d.ts.map