@scotthuang/agent-knock-knock 0.14.2 → 0.14.3

package/dist/src/claude-native-public-projection.d.ts

@@ -0,0 +1,605 @@
+import { type ClaudeNativeCatalogEntry } from "./claude-native-identity.js";
+import type { ClaudeNativeSnapshot, ClaudeNativePublicProgress } from "./claude-native-observation.js";
+import type { ClaudeNativeTaskRecord } from "./claude-native-state-store.js";
+/** The no-snapshot form is List-safe: no transcript read or progress/answer body. */
+export declare function claudeNativeSessionProjection(entry: ClaudeNativeCatalogEntry, snapshot?: ClaudeNativeSnapshot): {
+    waiting_for: string | null;
+    attention_required: boolean;
+    manual_required: boolean;
+    interaction_requests_scanned: boolean;
+    pending_interaction_count: null;
+    interaction_hint?: {
+        kind: string;
+        actionable: boolean;
+        source: string;
+    } | undefined;
+    next_action?: string | undefined;
+    id: string;
+    conversation_id: string;
+    source: string;
+    agent: string;
+    title: string;
+    cwd: string;
+    native_thread_id: string;
+    pid: number;
+    agent_version: string;
+    connection_state: string;
+    activity_state: "idle" | "unknown" | "waiting" | "working";
+    observed_at: string;
+    capabilities: {
+        interaction_notify: false;
+        interaction_respond: false;
+        approve: false;
+        model_options: false;
+        set_model: false;
+        permission_options: false;
+        set_permissions: false;
+        cancel: false;
+        new_thread: false;
+        clear_thread: false;
+        resume_thread: false;
+        list_resumable_threads: false;
+        status: boolean;
+        send: boolean;
+        watch: boolean;
+    };
+    available_actions: {
+        status: {
+            tool: string;
+            input: {
+                conversation_id: string;
+            };
+        };
+        send?: {
+            tool: string;
+            input: {
+                conversation_id: string;
+            };
+        } | undefined;
+        watch?: {
+            tool: string;
+            input: {
+                conversation_id: string;
+            };
+        } | undefined;
+    };
+    native_input_id?: string | null | undefined;
+    task_anchor_kind?: string | undefined;
+    read_at?: string | undefined;
+    observation_error?: string | undefined;
+    input_state?: "completed" | "failed" | "inProgress" | "interrupted" | "unknown" | undefined;
+    input_is_latest?: boolean | undefined;
+    response_text?: string | undefined;
+    response_truncated?: boolean | undefined;
+    progress?: ClaudeNativePublicProgress | undefined;
+};
+/** Send's internal Watch is the only completion monitor, never a second hidden subscription. */
+export declare function claudeNativeTaskProjection(task: ClaudeNativeTaskRecord, includeProgress?: boolean): {
+    task_kind: "send" | "watch";
+    turn_id?: string | undefined;
+    management_state: string;
+    deadline_at: string;
+    renewal_count: number;
+    closed_at: string | undefined;
+    close_reason: string | undefined;
+    unwatched_at: string | undefined;
+    renewed_at: string | undefined;
+    recovered_at: string | undefined;
+    callback_in_flight: boolean;
+    retryable_callback_ids: string[];
+    callback_state: string;
+    callback_delivery_scope: "controller_acceptance_only";
+    channel_delivery_state: "unknown";
+    callback_notifications: {
+        id: string;
+        notification_id: string;
+        status: string;
+        attempts: number;
+        controller_acceptance: string;
+        error_code?: string | undefined;
+        request_dispatched?: boolean | undefined;
+        request_phase?: string | undefined;
+        retry_budget_exhausted?: boolean | undefined;
+        max_delivery_attempts?: number | undefined;
+        next_attempt_at?: string | undefined;
+        automatic_retry_stopped?: boolean | undefined;
+    }[];
+    waiting_for: string | null;
+    attention_required: boolean;
+    manual_required: boolean;
+    interaction_requests_scanned: boolean;
+    pending_interaction_count: null;
+    interaction_hint?: {
+        kind: string;
+        actionable: boolean;
+        source: string;
+    } | undefined;
+    watch_id: string;
+    conversation_id: string;
+    source: string;
+    agent: string;
+    status: string;
+    observation_state: string;
+    task_origin: "send" | "watch";
+    observation_status: import("./claude-native-state-store.js").ClaudeNativeTaskStatus;
+    observation_active: boolean;
+    native_thread_id: string;
+    native_input_id: string | null;
+    task_anchor_kind: string;
+    observation_mode: string;
+    anchor_state: string;
+    needs_watch: boolean;
+    next_action: string;
+    created_at: string;
+    updated_at: string;
+    observed_at: string | undefined;
+    observation_error: string | undefined;
+    callback_configured: boolean;
+    callback_expected: boolean;
+    capabilities: {
+        interaction_notify: false;
+        interaction_respond: false;
+        approve: false;
+        model_options: false;
+        set_model: false;
+        permission_options: false;
+        set_permissions: false;
+        cancel: false;
+        new_thread: false;
+        clear_thread: false;
+        resume_thread: false;
+        list_resumable_threads: false;
+        status: boolean;
+        close: boolean;
+        unwatch: boolean;
+        renew: boolean;
+        recover: boolean;
+        retry_callback: boolean;
+        callback: boolean;
+    };
+    available_actions: {
+        recover?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        unwatch?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        close?: {
+            tool: string;
+            input: {
+                turn_id: string;
+            };
+        } | undefined;
+        retry_callback?: {
+            tool: string;
+            input: {
+                watch_id: string;
+                notification_id: string;
+            };
+        } | undefined;
+        renew?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        status: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        };
+    };
+    message_id?: undefined;
+    delivered?: undefined;
+    send_state?: undefined;
+    delivery_receipt?: undefined;
+    agent_acceptance?: undefined;
+    send_error?: undefined;
+    resend_allowed?: undefined;
+    response_text: string;
+    response_truncated: boolean;
+    progress: ClaudeNativePublicProgress | undefined;
+} | {
+    task_kind: "send" | "watch";
+    turn_id?: string | undefined;
+    management_state: string;
+    deadline_at: string;
+    renewal_count: number;
+    closed_at: string | undefined;
+    close_reason: string | undefined;
+    unwatched_at: string | undefined;
+    renewed_at: string | undefined;
+    recovered_at: string | undefined;
+    callback_in_flight: boolean;
+    retryable_callback_ids: string[];
+    callback_state: string;
+    callback_delivery_scope: "controller_acceptance_only";
+    channel_delivery_state: "unknown";
+    callback_notifications: {
+        id: string;
+        notification_id: string;
+        status: string;
+        attempts: number;
+        controller_acceptance: string;
+        error_code?: string | undefined;
+        request_dispatched?: boolean | undefined;
+        request_phase?: string | undefined;
+        retry_budget_exhausted?: boolean | undefined;
+        max_delivery_attempts?: number | undefined;
+        next_attempt_at?: string | undefined;
+        automatic_retry_stopped?: boolean | undefined;
+    }[];
+    waiting_for: string | null;
+    attention_required: boolean;
+    manual_required: boolean;
+    interaction_requests_scanned: boolean;
+    pending_interaction_count: null;
+    interaction_hint?: {
+        kind: string;
+        actionable: boolean;
+        source: string;
+    } | undefined;
+    watch_id: string;
+    conversation_id: string;
+    source: string;
+    agent: string;
+    status: string;
+    observation_state: string;
+    task_origin: "send" | "watch";
+    observation_status: import("./claude-native-state-store.js").ClaudeNativeTaskStatus;
+    observation_active: boolean;
+    native_thread_id: string;
+    native_input_id: string | null;
+    task_anchor_kind: string;
+    observation_mode: string;
+    anchor_state: string;
+    needs_watch: boolean;
+    next_action: string;
+    created_at: string;
+    updated_at: string;
+    observed_at: string | undefined;
+    observation_error: string | undefined;
+    callback_configured: boolean;
+    callback_expected: boolean;
+    capabilities: {
+        interaction_notify: false;
+        interaction_respond: false;
+        approve: false;
+        model_options: false;
+        set_model: false;
+        permission_options: false;
+        set_permissions: false;
+        cancel: false;
+        new_thread: false;
+        clear_thread: false;
+        resume_thread: false;
+        list_resumable_threads: false;
+        status: boolean;
+        close: boolean;
+        unwatch: boolean;
+        renew: boolean;
+        recover: boolean;
+        retry_callback: boolean;
+        callback: boolean;
+    };
+    available_actions: {
+        recover?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        unwatch?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        close?: {
+            tool: string;
+            input: {
+                turn_id: string;
+            };
+        } | undefined;
+        retry_callback?: {
+            tool: string;
+            input: {
+                watch_id: string;
+                notification_id: string;
+            };
+        } | undefined;
+        renew?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        status: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        };
+    };
+    message_id?: undefined;
+    delivered?: undefined;
+    send_state?: undefined;
+    delivery_receipt?: undefined;
+    agent_acceptance?: undefined;
+    send_error?: undefined;
+    resend_allowed?: undefined;
+    response_text?: undefined;
+    response_truncated?: undefined;
+    progress?: undefined;
+} | {
+    task_kind: "send" | "watch";
+    turn_id?: string | undefined;
+    management_state: string;
+    deadline_at: string;
+    renewal_count: number;
+    closed_at: string | undefined;
+    close_reason: string | undefined;
+    unwatched_at: string | undefined;
+    renewed_at: string | undefined;
+    recovered_at: string | undefined;
+    callback_in_flight: boolean;
+    retryable_callback_ids: string[];
+    callback_state: string;
+    callback_delivery_scope: "controller_acceptance_only";
+    channel_delivery_state: "unknown";
+    callback_notifications: {
+        id: string;
+        notification_id: string;
+        status: string;
+        attempts: number;
+        controller_acceptance: string;
+        error_code?: string | undefined;
+        request_dispatched?: boolean | undefined;
+        request_phase?: string | undefined;
+        retry_budget_exhausted?: boolean | undefined;
+        max_delivery_attempts?: number | undefined;
+        next_attempt_at?: string | undefined;
+        automatic_retry_stopped?: boolean | undefined;
+    }[];
+    waiting_for: string | null;
+    attention_required: boolean;
+    manual_required: boolean;
+    interaction_requests_scanned: boolean;
+    pending_interaction_count: null;
+    interaction_hint?: {
+        kind: string;
+        actionable: boolean;
+        source: string;
+    } | undefined;
+    watch_id: string;
+    conversation_id: string;
+    source: string;
+    agent: string;
+    status: string;
+    observation_state: string;
+    task_origin: "send" | "watch";
+    observation_status: import("./claude-native-state-store.js").ClaudeNativeTaskStatus;
+    observation_active: boolean;
+    native_thread_id: string;
+    native_input_id: string | null;
+    task_anchor_kind: string;
+    observation_mode: string;
+    anchor_state: string;
+    needs_watch: boolean;
+    next_action: string;
+    created_at: string;
+    updated_at: string;
+    observed_at: string | undefined;
+    observation_error: string | undefined;
+    callback_configured: boolean;
+    callback_expected: boolean;
+    capabilities: {
+        interaction_notify: false;
+        interaction_respond: false;
+        approve: false;
+        model_options: false;
+        set_model: false;
+        permission_options: false;
+        set_permissions: false;
+        cancel: false;
+        new_thread: false;
+        clear_thread: false;
+        resume_thread: false;
+        list_resumable_threads: false;
+        status: boolean;
+        close: boolean;
+        unwatch: boolean;
+        renew: boolean;
+        recover: boolean;
+        retry_callback: boolean;
+        callback: boolean;
+    };
+    available_actions: {
+        recover?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        unwatch?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        close?: {
+            tool: string;
+            input: {
+                turn_id: string;
+            };
+        } | undefined;
+        retry_callback?: {
+            tool: string;
+            input: {
+                watch_id: string;
+                notification_id: string;
+            };
+        } | undefined;
+        renew?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        status: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        };
+    };
+    message_id: string;
+    delivered: boolean;
+    send_state: "accepted" | "attached" | "held" | "not_sent" | "refused" | "reserved" | "uncertain";
+    delivery_receipt: string;
+    agent_acceptance: string;
+    send_error: string | undefined;
+    resend_allowed: boolean;
+    response_text: string;
+    response_truncated: boolean;
+    progress: ClaudeNativePublicProgress | undefined;
+} | {
+    task_kind: "send" | "watch";
+    turn_id?: string | undefined;
+    management_state: string;
+    deadline_at: string;
+    renewal_count: number;
+    closed_at: string | undefined;
+    close_reason: string | undefined;
+    unwatched_at: string | undefined;
+    renewed_at: string | undefined;
+    recovered_at: string | undefined;
+    callback_in_flight: boolean;
+    retryable_callback_ids: string[];
+    callback_state: string;
+    callback_delivery_scope: "controller_acceptance_only";
+    channel_delivery_state: "unknown";
+    callback_notifications: {
+        id: string;
+        notification_id: string;
+        status: string;
+        attempts: number;
+        controller_acceptance: string;
+        error_code?: string | undefined;
+        request_dispatched?: boolean | undefined;
+        request_phase?: string | undefined;
+        retry_budget_exhausted?: boolean | undefined;
+        max_delivery_attempts?: number | undefined;
+        next_attempt_at?: string | undefined;
+        automatic_retry_stopped?: boolean | undefined;
+    }[];
+    waiting_for: string | null;
+    attention_required: boolean;
+    manual_required: boolean;
+    interaction_requests_scanned: boolean;
+    pending_interaction_count: null;
+    interaction_hint?: {
+        kind: string;
+        actionable: boolean;
+        source: string;
+    } | undefined;
+    watch_id: string;
+    conversation_id: string;
+    source: string;
+    agent: string;
+    status: string;
+    observation_state: string;
+    task_origin: "send" | "watch";
+    observation_status: import("./claude-native-state-store.js").ClaudeNativeTaskStatus;
+    observation_active: boolean;
+    native_thread_id: string;
+    native_input_id: string | null;
+    task_anchor_kind: string;
+    observation_mode: string;
+    anchor_state: string;
+    needs_watch: boolean;
+    next_action: string;
+    created_at: string;
+    updated_at: string;
+    observed_at: string | undefined;
+    observation_error: string | undefined;
+    callback_configured: boolean;
+    callback_expected: boolean;
+    capabilities: {
+        interaction_notify: false;
+        interaction_respond: false;
+        approve: false;
+        model_options: false;
+        set_model: false;
+        permission_options: false;
+        set_permissions: false;
+        cancel: false;
+        new_thread: false;
+        clear_thread: false;
+        resume_thread: false;
+        list_resumable_threads: false;
+        status: boolean;
+        close: boolean;
+        unwatch: boolean;
+        renew: boolean;
+        recover: boolean;
+        retry_callback: boolean;
+        callback: boolean;
+    };
+    available_actions: {
+        recover?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        unwatch?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        close?: {
+            tool: string;
+            input: {
+                turn_id: string;
+            };
+        } | undefined;
+        retry_callback?: {
+            tool: string;
+            input: {
+                watch_id: string;
+                notification_id: string;
+            };
+        } | undefined;
+        renew?: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        } | undefined;
+        status: {
+            tool: string;
+            input: {
+                watch_id: string;
+            };
+        };
+    };
+    message_id: string;
+    delivered: boolean;
+    send_state: "accepted" | "attached" | "held" | "not_sent" | "refused" | "reserved" | "uncertain";
+    delivery_receipt: string;
+    agent_acceptance: string;
+    send_error: string | undefined;
+    resend_allowed: boolean;
+    response_text?: undefined;
+    response_truncated?: undefined;
+    progress?: undefined;
+};

package/dist/src/claude-native-public-projection.js

@@ -0,0 +1,98 @@
+import { backendObservationStopped, backendTaskRecoveryProjection, isBackendCallbackRetryable } from "./backend-task-recovery.js";
+import { backendCallbackPublicProjection } from "./backend-callback-public-projection.js";
+import { createClaudeNativeConversationId } from "./claude-native-identity.js";
+const specialCapabilities = {
+    interaction_notify: false, interaction_respond: false, approve: false,
+    model_options: false, set_model: false, permission_options: false, set_permissions: false,
+    cancel: false, new_thread: false, clear_thread: false, resume_thread: false, list_resumable_threads: false
+};
+const activeStatus = (status) => status === "watching" || status === "awaiting_acceptance";
+const settledStatus = (status) => ["completed", "failed", "interrupted", "exited"].includes(status);
+function waitingProjection(waitingFor, waiting) {
+    const kind = waitingFor === "permission prompt" ? "approval" : waitingFor === "input needed" ? "input" : "unknown";
+    return { waiting_for: !waiting ? null : kind === "approval" ? "permission prompt" : kind === "input" ? "input needed" : "unknown",
+        attention_required: waiting, manual_required: waiting,
+        interaction_requests_scanned: false, pending_interaction_count: null,
+        ...(waiting ? { interaction_hint: { kind, actionable: false, source: "native_registry" },
+            next_action: "return_to_claude_terminal" } : {}) };
+}
+/** The no-snapshot form is List-safe: no transcript read or progress/answer body. */
+export function claudeNativeSessionProjection(entry, snapshot) {
+    const id = createClaudeNativeConversationId(entry);
+    const selected = snapshot?.selectedInput;
+    const current = selected?.inputUuid === snapshot?.latestInputUuid;
+    const watching = entry.status === "working" || entry.status === "waiting";
+    const canWatch = watching && (!snapshot || !snapshot.readError && current && selected?.kind === "root_user" && selected.state === "inProgress");
+    const canSend = entry.status === "idle";
+    return {
+        id, conversation_id: id, source: "claude_cli", agent: "claude",
+        title: entry.name ?? "Claude Code", cwd: entry.cwd,
+        native_thread_id: entry.sessionId, pid: entry.pid, agent_version: entry.version,
+        connection_state: "native_registry_verified", activity_state: entry.status, observed_at: entry.observedAt,
+        ...waitingProjection(entry.waitingFor, entry.status === "waiting"),
+        capabilities: { status: true, send: canSend, watch: canWatch, ...specialCapabilities },
+        available_actions: {
+            status: { tool: "agent_knock_knock_status", input: { conversation_id: id } },
+            ...(canSend ? { send: { tool: "agent_knock_knock_send", input: { conversation_id: id } } } : {}),
+            ...(canWatch ? { watch: { tool: "agent_knock_knock_watch", input: { conversation_id: id } } } : {})
+        },
+        ...(snapshot ? {
+            native_input_id: selected?.inputUuid ?? null, task_anchor_kind: "native_input_uuid",
+            read_at: snapshot.readAt, observation_error: snapshot.readError ?? selected?.reason,
+            input_state: selected?.state ?? "unknown", input_is_latest: current,
+            response_text: selected?.responseText ?? "", response_truncated: selected?.responseTruncated ?? false,
+            progress: snapshot.progress
+        } : {})
+    };
+}
+/** Send's internal Watch is the only completion monitor, never a second hidden subscription. */
+export function claudeNativeTaskProjection(task, includeProgress = false) {
+    const { recovery_actions: commonActions, ...recovery } = backendTaskRecoveryProjection(task);
+    const stopped = backendObservationStopped(task), active = !stopped && activeStatus(task.status);
+    const settled = settledStatus(task.status);
+    const canRenew = !task.closed_at && !settled;
+    const { renew: commonRenew, ...otherActions } = commonActions;
+    const recoveryActions = { ...otherActions, ...(canRenew && commonRenew ? { renew: commonRenew } : {}) };
+    const nextAction = active ? "wait_or_status" : task.status === "timed_out" && canRenew ? "renew_existing_watch"
+        : task.status === "exited" ? "return_to_claude_terminal" : "none";
+    return {
+        watch_id: task.id, conversation_id: task.native_id, source: "claude_cli", agent: "claude",
+        status: task.closed_at ? "closed" : task.status, ...recovery,
+        observation_state: stopped ? "stopped" : settled ? "settled" : task.status === "timed_out" ? "expired" : "watching",
+        task_origin: task.kind, observation_status: task.status, observation_active: active,
+        native_thread_id: task.target.sessionId, native_input_id: task.native_input_id ?? null,
+        task_anchor_kind: "native_input_uuid", observation_mode: task.native_input_id ? "exact_task" : "pending_acceptance",
+        anchor_state: task.native_input_id ? "verified" : "pending", needs_watch: false, next_action: nextAction,
+        created_at: task.created_at, updated_at: task.updated_at, observed_at: task.observed_at,
+        observation_error: task.observation_error,
+        ...waitingProjection(task.waiting_for, active && Boolean(task.waiting_for)),
+        callback_configured: Boolean(task.callback_route), callback_expected: callbackExpected(task, active, stopped),
+        ...backendCallbackPublicProjection(task, active, stopped),
+        capabilities: { status: true, close: task.kind === "send" && !task.closed_at, unwatch: !stopped,
+            renew: canRenew, recover: !task.closed_at,
+            retry_callback: task.notifications.some(note => isBackendCallbackRetryable(task, note)),
+            callback: Boolean(task.callback_route) && !stopped, ...specialCapabilities },
+        available_actions: {
+            status: { tool: "agent_knock_knock_status", input: { watch_id: task.id } }, ...recoveryActions
+        },
+        ...sendProjection(task), ...bodyProjection(task, includeProgress)
+    };
+}
+function sendProjection(task) {
+    const intent = task.send_intent;
+    if (!intent)
+        return {};
+    const accepted = intent.state === "accepted";
+    return { message_id: intent.message_id, delivered: accepted, send_state: intent.state,
+        delivery_receipt: accepted ? "native_task_verified" : intent.state === "not_sent" ? "not_sent" : "acceptance_unproven",
+        agent_acceptance: accepted ? "proven" : "unproven", send_error: intent.error_code, resend_allowed: false };
+}
+function bodyProjection(task, includeProgress) {
+    return includeProgress ? { response_text: task.response_text ?? "", response_truncated: task.response_truncated ?? false,
+        progress: task.progress } : {};
+}
+function callbackExpected(task, active, stopped) {
+    const pending = task.notifications.some(note => ["ready", "leased", "retry_wait"].includes(note.status));
+    return Boolean(task.callback_route && !stopped && (active || pending));
+}
+//# sourceMappingURL=claude-native-public-projection.js.map