@scotthuang/agent-knock-knock 0.13.17 → 0.14.0

package/dist/src/desktop-control-semantic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-control-semantic.js","sourceRoot":"","sources":["../../src/desktop-control-semantic.ts"],"names":[],"mappings":"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"}

package/dist/src/desktop-identity.d.ts

@@ -0,0 +1,5 @@
+import type { DesktopThreadIdentity } from "./desktop-types.js";
+/** Desktop identity is independent of a window, mutable title, or current IPC owner. */
+export declare function createDesktopConversationId(identity: DesktopThreadIdentity): string;
+export declare function parseDesktopConversationId(value: string): DesktopThreadIdentity;
+export declare function isDesktopConversationId(value: unknown): value is string;

package/dist/src/desktop-identity.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+const PREFIX = "desktop:v1:";
+/** Desktop identity is independent of a window, mutable title, or current IPC owner. */
+export function createDesktopConversationId(identity) {
+    const value = validate(identity);
+    return PREFIX + Buffer.from(JSON.stringify([value.codexHome, value.hostId, value.threadId])).toString("base64url");
+}
+export function parseDesktopConversationId(value) {
+    if (!isDesktopConversationId(value) || value.length > 4096)
+        throw new Error("Invalid Desktop conversation ID");
+    const encoded = value.slice(PREFIX.length);
+    if (!/^[A-Za-z0-9_-]+$/u.test(encoded))
+        throw new Error("Invalid Desktop conversation ID encoding");
+    let tuple;
+    try {
+        tuple = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new Error("Invalid Desktop conversation ID payload");
+    }
+    if (!Array.isArray(tuple) || tuple.length !== 3)
+        throw new Error("Invalid Desktop conversation ID payload");
+    const identity = validate({ codexHome: tuple[0], hostId: tuple[1], threadId: tuple[2] });
+    if (createDesktopConversationId(identity) !== value)
+        throw new Error("Non-canonical Desktop conversation ID");
+    return identity;
+}
+export function isDesktopConversationId(value) {
+    return typeof value === "string" && value.startsWith(PREFIX);
+}
+function validate(value) {
+    if (typeof value.codexHome !== "string" || !path.isAbsolute(value.codexHome) ||
+        /[\u0000-\u001f\u007f]/u.test(value.codexHome) || value.codexHome.length > 2048 ||
+        typeof value.hostId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u.test(value.hostId) ||
+        typeof value.threadId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{1,160}$/u.test(value.threadId)) {
+        throw new Error("Invalid Desktop native identity");
+    }
+    return { codexHome: path.resolve(value.codexHome), hostId: value.hostId, threadId: value.threadId };
+}
+//# sourceMappingURL=desktop-identity.js.map

package/dist/src/desktop-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-identity.js","sourceRoot":"","sources":["../../src/desktop-identity.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,MAAM,MAAM,GAAG,aAAa,CAAC;AAE7B,wFAAwF;AACxF,MAAM,UAAU,2BAA2B,CAAC,QAA+B;IACzE,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACjC,OAAO,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACrH,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,KAAa;IACtD,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAC/G,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IACpG,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAAC,CAAC;IAC/E,MAAM,CAAC;QAAC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAAC,CAAC;IACrE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC5G,MAAM,QAAQ,GAAG,QAAQ,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACzF,IAAI,2BAA2B,CAAC,QAAQ,CAAC,KAAK,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC9G,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAC/D,CAAC;AAED,SAAS,QAAQ,CAAC,KAA4B;IAC5C,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,CAAC;QACxE,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI;QAC/E,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,sCAAsC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QAC9F,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,oCAAoC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrG,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;AACtG,CAAC"}

package/dist/src/desktop-interaction-projection.d.ts

@@ -0,0 +1,57 @@
+import type { DesktopAsyncInteraction, DesktopInteraction, DesktopRequestResponse } from "./desktop-types.js";
+type ProjectedQuestion = {
+    question_id: string;
+    title: string;
+    response_kind: string;
+    allow_free_text: boolean;
+    is_secret?: boolean;
+    options: {
+        option_id: string;
+        label: string;
+    }[];
+};
+export interface ProjectedDesktopInteraction {
+    conversation_id?: string;
+    watch_id?: string;
+    interaction_id: string;
+    kind: DesktopInteraction["kind"];
+    status: "pending";
+    native_thread_id: string;
+    native_turn_id: string;
+    delivery_modes?: string[];
+    expires_at: string;
+    interaction_prompt_fingerprint: string;
+    questions: ProjectedQuestion[];
+    command?: string;
+    reason?: string;
+    cwd?: string;
+    network?: {
+        host: string;
+        protocol: string;
+    };
+    file_changes?: {
+        path: string;
+        kind?: string;
+        diff?: string;
+        diffTruncated?: boolean;
+    }[];
+    available_actions: Record<string, {
+        tool: string;
+        input: Record<string, string>;
+    }>;
+}
+export declare function desktopInteractionIsApproval(item: {
+    kind: string;
+}): boolean;
+/** Exact request content, never stream revision or elapsed time, defines freshness. */
+export declare function desktopInteractionFingerprint(item: DesktopInteraction): string;
+export declare function desktopInteractionProjection(item: DesktopInteraction, desktopId: string, watchId?: string): ProjectedDesktopInteraction;
+/** Reconstruct a whitelist after checking exact subject and task; raw request fields never escape. */
+export declare function validateDesktopInteractionProjections(value: unknown, desktopId: unknown, watchId?: unknown, turnId?: unknown): ProjectedDesktopInteraction[];
+export declare function desktopQuestionAnswer(interaction: DesktopAsyncInteraction, value: unknown): string;
+/** Answer every question from one exact native request in a single structured response. */
+export declare function desktopQuestionResponse(interaction: DesktopInteraction, value: unknown): Extract<DesktopRequestResponse, {
+    answers: unknown;
+}>;
+export declare function validateDesktopProjectedAnswer(projection: ProjectedDesktopInteraction, value: unknown): void;
+export {};

package/dist/src/desktop-interaction-projection.js

@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import { parseDesktopConversationId } from "./desktop-identity.js";
+import { isRecord } from "./value-guards.js";
+const digest = (parts) => createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+const questionId = (item, nativeId) => `q:${digest([item.id, nativeId])}`;
+const optionId = (item, nativeId, label) => `o:${digest([item.id, nativeId, label])}`;
+const interactionPattern = /^desktop-(?:async|request)-interaction:[0-9a-f]{64}$/u;
+const questionPattern = /^q:[0-9a-f]{64}$/u;
+const optionPattern = /^o:[0-9a-f]{64}$/u;
+export function desktopInteractionIsApproval(item) {
+    return item.kind === "command_approval" || item.kind === "file_approval";
+}
+/** Exact request content, never stream revision or elapsed time, defines freshness. */
+export function desktopInteractionFingerprint(item) {
+    const request = item.kind === "async_question" ? [] : [item.requestId, item.command, item.reason, item.cwd,
+        item.approvalId, item.nativeApprovalKind, item.networkApprovalContext, item.changes];
+    return digest([item.id, item.threadId, item.turnId, item.itemId, item.method, item.questions, ...request]);
+}
+export function desktopInteractionProjection(item, desktopId, watchId) {
+    const target = watchId ? { watch_id: watchId } : { conversation_id: desktopId };
+    const approval = desktopInteractionIsApproval(item);
+    return {
+        ...target, interaction_id: item.id, kind: item.kind, status: "pending",
+        native_thread_id: item.threadId, native_turn_id: item.turnId,
+        ...(item.kind === "async_question" ? { delivery_modes: ["steer_current_turn"] } : {}),
+        ...(item.kind === "async_question" ? {} : approvalDetails(item)),
+        expires_at: new Date(Date.now() + 10 * 60_000).toISOString(),
+        interaction_prompt_fingerprint: desktopInteractionFingerprint(item),
+        questions: item.questions.map(question => desktopQuestionProjection(item, question)),
+        available_actions: { [approval ? "approve" : "respond"]: {
+                tool: approval ? "agent_knock_knock_approve" : "agent_knock_knock_respond_interaction",
+                input: { ...target, interaction_id: item.id }
+            } }
+    };
+}
+function approvalDetails(item) {
+    return { ...(item.command ? { command: item.command } : {}), ...(item.reason ? { reason: item.reason } : {}),
+        ...(item.cwd ? { cwd: item.cwd } : {}), ...(item.networkApprovalContext ? { network: item.networkApprovalContext } : {}),
+        ...(item.changes ? { file_changes: item.changes } : {}) };
+}
+function desktopQuestionProjection(item, question) {
+    return { question_id: questionId(item, question.id), title: question.title,
+        response_kind: question.options.length ? "single_select" : "free_text",
+        allow_free_text: !question.options.length || question.isOther === true || item.kind === "async_question",
+        ...(question.isSecret ? { is_secret: true } : {}),
+        options: question.options.map(label => ({ option_id: optionId(item, question.id, label), label })) };
+}
+/** Reconstruct a whitelist after checking exact subject and task; raw request fields never escape. */
+export function validateDesktopInteractionProjections(value, desktopId, watchId, turnId) {
+    if (typeof desktopId !== "string" || !Array.isArray(value) || value.length > 128)
+        throw new Error("Invalid Desktop interaction projection");
+    const identity = parseDesktopConversationId(desktopId);
+    if (watchId !== undefined && (typeof watchId !== "string" || !/^desktop-watch:[A-Za-z0-9_-]{8,128}$/u.test(watchId)))
+        throw new Error("Invalid Desktop Watch identity");
+    const ids = new Set();
+    return value.map(item => {
+        assertProjectedInteraction(item, { desktopId, watchId, threadId: identity.threadId, turnId });
+        if (ids.has(item.interaction_id))
+            throw new Error("Duplicate Desktop interaction");
+        ids.add(item.interaction_id);
+        return copyProjectedInteraction(item, desktopId, typeof watchId === "string" ? watchId : undefined);
+    });
+}
+function copyProjectedInteraction(item, desktopId, watchId) {
+    const target = watchId ? { watch_id: watchId } : { conversation_id: desktopId };
+    const approval = desktopInteractionIsApproval(item);
+    return { ...copyProjectedApprovalDetails(item), ...target, interaction_id: item.interaction_id, kind: item.kind, status: "pending",
+        native_thread_id: item.native_thread_id, native_turn_id: item.native_turn_id,
+        ...(item.kind === "async_question" ? { delivery_modes: ["steer_current_turn"] } : {}),
+        expires_at: item.expires_at,
+        interaction_prompt_fingerprint: item.interaction_prompt_fingerprint,
+        questions: item.questions.map(q => ({ question_id: q.question_id, title: q.title, response_kind: q.response_kind,
+            allow_free_text: q.allow_free_text, ...(q.is_secret ? { is_secret: true } : {}),
+            options: q.options.map(o => ({ option_id: o.option_id, label: o.label })) })),
+        available_actions: { [approval ? "approve" : "respond"]: {
+                tool: approval ? "agent_knock_knock_approve" : "agent_knock_knock_respond_interaction",
+                input: { ...target, interaction_id: item.interaction_id }
+            } } };
+}
+function copyProjectedApprovalDetails(item) {
+    const details = {};
+    for (const field of ["command", "reason", "cwd"]) {
+        if (typeof item[field] === "string")
+            details[field] = item[field];
+    }
+    if (isRecord(item.network) && typeof item.network.host === "string" && typeof item.network.protocol === "string") {
+        details.network = { host: item.network.host, protocol: item.network.protocol };
+    }
+    if (Array.isArray(item.file_changes))
+        details.file_changes = item.file_changes
+            .filter(change => isRecord(change) && typeof change.path === "string").map(projectedFileChange);
+    return details;
+}
+function projectedFileChange(change) {
+    return { path: change.path, ...(typeof change.kind === "string" ? { kind: change.kind } : {}),
+        ...(typeof change.diff === "string" ? { diff: change.diff } : {}), ...(change.diffTruncated === true ? { diffTruncated: true } : {}) };
+}
+function assertProjectedInteraction(item, target) {
+    if (!isRecord(item) || typeof item.interaction_id !== "string" || !interactionPattern.test(item.interaction_id)
+        || !["async_question", "blocking_question", "command_approval", "file_approval"].includes(String(item.kind))
+        || item.status !== "pending" || item.native_thread_id !== target.threadId
+        || typeof item.native_turn_id !== "string" || !item.native_turn_id || (typeof target.turnId === "string" && item.native_turn_id !== target.turnId)
+        || (target.watchId ? item.watch_id !== target.watchId : item.conversation_id !== target.desktopId))
+        throw new Error("Desktop interaction identity mismatch");
+    if ((item.kind === "async_question") !== item.interaction_id.startsWith("desktop-async-interaction:"))
+        throw new Error("Desktop interaction identity mismatch");
+    assertProjectedQuestionDetails(item);
+}
+function assertProjectedQuestionDetails(item) {
+    if (!Array.isArray(item.questions) || item.questions.length > 16 || typeof item.expires_at !== "string"
+        || !Number.isFinite(Date.parse(item.expires_at)))
+        throw new Error("Invalid Desktop interaction projection");
+    if (item.kind === "async_question" && (item.questions.length !== 1 || !Array.isArray(item.delivery_modes)
+        || item.delivery_modes.length !== 1 || item.delivery_modes[0] !== "steer_current_turn"))
+        throw new Error("Invalid Desktop async projection");
+    if (item.kind !== "async_question" && item.delivery_modes !== undefined)
+        throw new Error("Blocking Desktop interactions cannot steer replies");
+    if (item.kind === "blocking_question" && !item.questions.length)
+        throw new Error("Empty Desktop questionnaire");
+    if (["command_approval", "file_approval"].includes(String(item.kind)) && item.questions.length)
+        throw new Error("Desktop approval cannot contain question answers");
+    const ids = new Set();
+    for (const question of item.questions) {
+        assertProjectedQuestion(question);
+        if (ids.has(question.question_id))
+            throw new Error("Duplicate Desktop question");
+        ids.add(question.question_id);
+    }
+}
+function assertProjectedQuestion(q) {
+    if (!isRecord(q) || typeof q.question_id !== "string" || !questionPattern.test(q.question_id)
+        || typeof q.title !== "string" || !q.title || !["single_select", "free_text"].includes(String(q.response_kind))
+        || typeof q.allow_free_text !== "boolean" || !Array.isArray(q.options) || q.options.length > 32
+        || q.options.some(option => !validProjectedOption(option)))
+        throw new Error("Invalid Desktop question");
+}
+function validProjectedOption(option) {
+    return isRecord(option) && typeof option.option_id === "string" && optionPattern.test(option.option_id) && typeof option.label === "string";
+}
+export function desktopQuestionAnswer(interaction, value) {
+    const answers = desktopQuestionResponse(interaction, value);
+    return answers.answers[interaction.questions[0].id][0];
+}
+/** Answer every question from one exact native request in a single structured response. */
+export function desktopQuestionResponse(interaction, value) {
+    const projection = desktopInteractionProjection(interaction, "unused");
+    const selected = projectedAnswers(projection, value);
+    const answers = {};
+    for (const question of interaction.questions) {
+        Object.defineProperty(answers, question.id, { value: [selected.get(questionId(interaction, question.id))], enumerable: true });
+    }
+    return { answers };
+}
+export function validateDesktopProjectedAnswer(projection, value) {
+    projectedAnswers(projection, value);
+}
+function projectedAnswers(projection, value) {
+    assertAnswerEnvelope(projection, value);
+    const answers = new Map();
+    for (const answer of value.answers) {
+        if (!isRecord(answer))
+            throw new Error("Invalid Desktop answer");
+        const question = projection.questions.find(q => q.question_id === answer.question_id);
+        if (!question || answers.has(question.question_id))
+            throw new Error("Desktop question ID does not match or is duplicated");
+        answers.set(question.question_id, projectedDesktopAnswerText(question, answer));
+    }
+    return answers;
+}
+function assertAnswerEnvelope(projection, value) {
+    if (desktopInteractionIsApproval(projection) || !isRecord(value) || value.interaction_id !== projection.interaction_id
+        || !Array.isArray(value.answers) || value.answers.length !== projection.questions.length
+        || Object.keys(value).some(key => !["interaction_id", "answers", "delivery_mode"].includes(key)))
+        throw new Error("Answer must match every question in one current Desktop interaction");
+    if (value.delivery_mode !== undefined && (projection.kind !== "async_question" || value.delivery_mode !== "steer_current_turn")) {
+        throw new Error("Answer must use one current Desktop async delivery mode");
+    }
+}
+function projectedDesktopAnswerText(question, answer) {
+    if (answer.response_kind === "single_select") {
+        if (Object.keys(answer).some(key => !["question_id", "response_kind", "selected_option_ids"].includes(key))
+            || !Array.isArray(answer.selected_option_ids) || answer.selected_option_ids.length !== 1)
+            throw new Error("Select one advertised Desktop option");
+        const option = question.options.find(item => item.option_id === answer.selected_option_ids[0]);
+        if (!option)
+            throw new Error("Selected Desktop option is absent");
+        return option.label;
+    }
+    if (answer.response_kind !== "free_text" || !question.allow_free_text
+        || Object.keys(answer).some(key => !["question_id", "response_kind", "text"].includes(key))
+        || typeof answer.text !== "string" || !answer.text.trim() || answer.text.length > 4096
+        || /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/u.test(answer.text))
+        throw new Error("Invalid Desktop free-text answer");
+    return answer.text;
+}
+//# sourceMappingURL=desktop-interaction-projection.js.map

package/dist/src/desktop-interaction-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-interaction-projection.js","sourceRoot":"","sources":["../../src/desktop-interaction-projection.ts"],"names":[],"mappings":"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"}

package/dist/src/desktop-interaction-state.d.ts

@@ -0,0 +1,3 @@
+import type { DesktopInteraction, DesktopThreadIdentity } from "./desktop-types.js";
+export declare function assertDesktopInteraction(value: unknown, target?: DesktopThreadIdentity, turnId?: string): asserts value is DesktopInteraction;
+export declare function persistDesktopInteraction(interaction: DesktopInteraction): DesktopInteraction;

package/dist/src/desktop-interaction-state.js

@@ -0,0 +1,48 @@
+import { assertDesktopAsyncInteraction, desktopNonblank } from "./desktop-async-state.js";
+import { desktopRequestInteractionId } from "./desktop-request-interactions.js";
+const methods = {
+    command_approval: "item/commandExecution/requestApproval",
+    file_approval: "item/fileChange/requestApproval",
+    blocking_question: "item/tool/requestUserInput"
+};
+function assertRequestIdentity(interaction) {
+    if (!interaction || !(interaction.kind in methods) || interaction.method !== methods[interaction.kind] ||
+        !desktopNonblank(interaction.id) || !desktopNonblank(interaction.threadId) || !desktopNonblank(interaction.turnId) ||
+        !desktopNonblank(interaction.itemId) || !Array.isArray(interaction.questions))
+        throw new Error("Invalid Desktop request interaction");
+    if (!(typeof interaction.requestId === "number" && Number.isSafeInteger(interaction.requestId)) &&
+        !desktopNonblank(interaction.requestId))
+        throw new Error("Desktop interaction requires its native request identity");
+}
+function assertRequestQuestions(interaction) {
+    if (interaction.kind === "blocking_question" && !interaction.questions.length)
+        throw new Error("Desktop blocking question has no questions");
+    if (interaction.kind !== "blocking_question" && interaction.questions.length)
+        throw new Error("Desktop approval cannot contain answer questions");
+    const ids = new Set();
+    for (const question of interaction.questions) {
+        if (!desktopNonblank(question.id) || !desktopNonblank(question.title) || ids.has(question.id) ||
+            !Array.isArray(question.options) || question.options.some(option => !desktopNonblank(option)))
+            throw new Error("Invalid Desktop blocking question");
+        ids.add(question.id);
+    }
+}
+export function assertDesktopInteraction(value, target, turnId) {
+    const interaction = value;
+    if (interaction?.kind === "async_question") {
+        assertDesktopAsyncInteraction(value, target, turnId);
+        return;
+    }
+    assertRequestIdentity(interaction);
+    assertRequestQuestions(interaction);
+    if (target && interaction.threadId !== target.threadId || turnId && interaction.turnId !== turnId) {
+        throw new Error("Desktop interaction belongs to a different native task");
+    }
+    if (interaction.id !== desktopRequestInteractionId(interaction))
+        throw new Error("Desktop request payload does not match its identity");
+}
+export function persistDesktopInteraction(interaction) {
+    assertDesktopInteraction(interaction);
+    return structuredClone(interaction);
+}
+//# sourceMappingURL=desktop-interaction-state.js.map

package/dist/src/desktop-interaction-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-interaction-state.js","sourceRoot":"","sources":["../../src/desktop-interaction-state.ts"],"names":[],"mappings":"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"}

package/dist/src/desktop-ipc-async-answer.d.ts

@@ -0,0 +1,9 @@
+import { type DesktopAsyncAnswerOptions, type DesktopAsyncAnswerReceipt, type DesktopObserveTarget, type DesktopOwner, type DesktopSnapshot } from "./desktop-types.js";
+export interface DesktopAsyncAnswerPort {
+    discoverOwner(threadId: string, ownerId: string): Promise<DesktopOwner>;
+    observeThread(target: DesktopObserveTarget): Promise<DesktopSnapshot>;
+    request(params: Record<string, unknown>, ownerId: string): Promise<Record<string, unknown>>;
+    markDispatched(): void;
+}
+/** One targeted steer attempt. An RPC acknowledgement is not the final native answer proof. */
+export declare function sendDesktopAsyncAnswer(options: DesktopAsyncAnswerOptions, port: DesktopAsyncAnswerPort): Promise<DesktopAsyncAnswerReceipt>;

package/dist/src/desktop-ipc-async-answer.js

@@ -0,0 +1,71 @@
+import { buildDesktopAsyncReply, desktopAsyncQuestions } from "./desktop-async-interactions.js";
+import { desktopRecord } from "./desktop-snapshot.js";
+import { DesktopIpcError } from "./desktop-types.js";
+function validateOptions(options) {
+    if (!Number.isSafeInteger(options.expectedRevision) || options.expectedRevision < 0
+        || typeof options.expectedTurnId !== "string" || !options.expectedTurnId
+        || typeof options.interactionId !== "string" || !options.interactionId
+        || typeof options.answer !== "string" || !options.answer.trim() || options.answer.length > 16_384) {
+        throw new DesktopIpcError("invalid_argument", "Invalid Desktop asynchronous response");
+    }
+}
+function activeQuestion(snapshot, options) {
+    const active = snapshot.turns.filter(turn => turn.status === "inProgress");
+    if (snapshot.threadId !== options.threadId || snapshot.ownerClientId !== options.ownerClientId
+        || snapshot.revision < options.expectedRevision || !snapshot.tailKnown || snapshot.mode !== "default"
+        || snapshot.resumeState !== "resumed" || snapshot.runtimeStatus !== "active"
+        || snapshot.latestTurnId !== options.expectedTurnId || active.length !== 1 || active[0].turnId !== options.expectedTurnId) {
+        throw new DesktopIpcError("stale_interaction", "Desktop asynchronous question no longer belongs to the exact active task");
+    }
+    const matches = desktopAsyncQuestions(snapshot, options.expectedTurnId).filter(question => question.id === options.interactionId);
+    if (matches.length !== 1)
+        throw new DesktopIpcError("stale_interaction", "Desktop asynchronous question is answered, changed, or unavailable");
+    if (snapshot.turns.some(turn => turn.items.some(item => item.clientId === options.clientUserMessageId
+        || item.clientUserMessageId === options.clientUserMessageId || item.serverClientUserMessageId === options.clientUserMessageId))) {
+        throw new DesktopIpcError("duplicate_submission", "Desktop already contains this answer identity; it will not be replayed");
+    }
+    return matches[0];
+}
+function steerParams(options, snapshot, text) {
+    const id = options.clientUserMessageId;
+    return { conversationId: options.threadId, input: [{ type: "text", text, text_elements: [] }],
+        clientUserMessageId: id, attachments: [], restoreMessage: {
+            id, text, createdAt: Date.now(), ...(snapshot.cwd ? { cwd: snapshot.cwd } : {}),
+            context: { prompt: text, addedFiles: [], fileAttachments: [], ideContext: null, imageAttachments: [],
+                commentAttachments: [], workspaceRoots: snapshot.cwd ? [snapshot.cwd] : [] }
+        } };
+}
+function receiptTurnId(response) {
+    const outer = response.result;
+    const result = desktopRecord(outer) ? outer.result : undefined;
+    return desktopRecord(result) && typeof result.turnId === "string" ? result.turnId : undefined;
+}
+/** One targeted steer attempt. An RPC acknowledgement is not the final native answer proof. */
+export async function sendDesktopAsyncAnswer(options, port) {
+    validateOptions(options);
+    const owner = await port.discoverOwner(options.threadId, options.ownerClientId);
+    if (!owner.supportsUntrustedAppInput)
+        throw new DesktopIpcError("incompatible_desktop", "Desktop owner does not support untrusted app input");
+    const baseline = await port.observeThread(options);
+    const question = activeQuestion(baseline, options);
+    const text = buildDesktopAsyncReply(question, options.answer);
+    await options.beforeDispatch?.(structuredClone(baseline));
+    // Normal progress changes revisions. Recheck the question and exact task, not byte-identical snapshots.
+    const current = await port.observeThread(options);
+    activeQuestion(current, options);
+    port.markDispatched();
+    try {
+        const response = await port.request(steerParams(options, current, text), options.ownerClientId);
+        const turnId = receiptTurnId(response);
+        if (turnId !== options.expectedTurnId) {
+            throw new DesktopIpcError("unexpected_existing_turn", "Desktop did not acknowledge the expected asynchronous answer task", "unknown", turnId);
+        }
+        return { turnId, clientUserMessageId: options.clientUserMessageId, revision: current.revision, atomicTurnPrecondition: false };
+    }
+    catch (error) {
+        if (error instanceof DesktopIpcError && error.dispatchState !== "not_sent")
+            throw error;
+        throw new DesktopIpcError(error instanceof DesktopIpcError ? error.code : "closed", error instanceof Error ? error.message : "Desktop asynchronous response outcome is unknown", "unknown");
+    }
+}
+//# sourceMappingURL=desktop-ipc-async-answer.js.map

package/dist/src/desktop-ipc-async-answer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-ipc-async-answer.js","sourceRoot":"","sources":["../../src/desktop-ipc-async-answer.ts"],"names":[],"mappings":"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"}

package/dist/src/desktop-ipc-client.d.ts

@@ -0,0 +1,47 @@
+import { type DesktopIpcClientOptions, type DesktopOwner, type DesktopObserveTarget, type DesktopSendTurnOptions, type DesktopSnapshot, type DesktopTurnReceipt, type DesktopAsyncAnswerOptions, type DesktopAsyncAnswerReceipt, type DesktopRequestOptions, type DesktopRequestReceipt, type DesktopModelSettings, type DesktopSettingsOptions, type DesktopSettingsReceipt, type DesktopInterruptOptions, type DesktopInterruptReceipt } from "./desktop-types.js";
+export declare const VERIFIED_DESKTOP_BUILD: Readonly<{
+    version: "26.1002.52244";
+    build: "13536";
+}>;
+/** Scoped native operations only; no generic RPC entry point or ownership acquisition. */
+export declare class DesktopIpcClient {
+    private readonly transport;
+    private readonly options;
+    private readonly timeoutMs;
+    private readonly pending;
+    private readonly unsubscribe;
+    private clientId;
+    private closed;
+    private target;
+    private snapshot;
+    private observedRevision;
+    private dirty;
+    private generation;
+    private sending;
+    private readonly sentMessageIds;
+    private snapshotWaiter;
+    private constructor();
+    static connect(options: DesktopIpcClientOptions): Promise<DesktopIpcClient>;
+    discoverOwner(threadId: string, expectedOwnerId?: string): Promise<DesktopOwner>;
+    observeThread(target: DesktopObserveTarget): Promise<DesktopSnapshot>;
+    sendTurnOnce(options: DesktopSendTurnOptions): Promise<DesktopTurnReceipt>;
+    answerAsyncOnce(options: DesktopAsyncAnswerOptions): Promise<DesktopAsyncAnswerReceipt>;
+    respondRequestOnce(options: DesktopRequestOptions): Promise<DesktopRequestReceipt>;
+    readModelSettings(target: DesktopObserveTarget): Promise<DesktopModelSettings>;
+    updateThreadSettingsOnce(options: DesktopSettingsOptions): Promise<DesktopSettingsReceipt>;
+    interruptTurnOnce(options: DesktopInterruptOptions): Promise<DesktopInterruptReceipt>;
+    private nativePort;
+    private nativeOperation;
+    private validateSubmission;
+    private validateWrite;
+    private prepareSubmission;
+    close(): void;
+    private assertOpen;
+    private follow;
+    private request;
+    private receive;
+    private receiveResponse;
+    private receiveStreamChange;
+    private finish;
+}
+export declare const connectDesktopIpcClient: typeof DesktopIpcClient.connect;