@cjhyy/code-shell-pet 0.8.0

package/dist/long-task.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Durable Pet long-task domain model.
+ *
+ * The package owns the state machine and the bounded context contract. Hosts
+ * own persistence, worker control, and UI transport. Keeping those effects out
+ * of this module lets Desktop and a future headless host share identical task
+ * semantics without teaching core about Pet.
+ */
+import type { PetWorkExecutionBackend } from "./delegation.js";
+export declare const PET_LONG_TASK_SCHEMA_VERSION: 1;
+export declare const MAX_PET_LONG_TASK_EVENTS = 120;
+export declare const MAX_PET_LONG_TASK_SUMMARY_LENGTH = 8000;
+export type PetLongTaskStatus = "queued" | "running" | "waiting" | "paused" | "interrupted" | "completed" | "failed" | "cancelled";
+export type PetLongTaskPhase = "planning" | "executing" | "waiting-user" | "waiting-worker" | "finalizing";
+export type PetLongTaskVerificationMode = "turn" | "goal";
+export interface PetLongTaskArtifact {
+    kind: "session" | "result" | "file" | "url";
+    label: string;
+    /** Opaque host reference. The Pet package never dereferences it. */
+    reference: string;
+}
+/** Host-owned delivery route for a proactive completion receipt. */
+export interface PetLongTaskCompletionTarget {
+    kind: "im-gateway";
+    channel: string;
+    target: string;
+    /** How this route renders a GatewayReply URL action. */
+    replyButton?: "native" | "link";
+    /** Host-mediated attachment kinds supported by the originating route. */
+    replyAttachmentKinds?: PetReplyAttachmentKind[];
+}
+export type PetReplyAttachmentKind = "image" | "file" | "audio" | "video";
+export type PetLongTaskEventKind = "created" | "started" | "progress" | "waiting" | "paused" | "resumed" | "retrying" | "artifact" | "checkpoint" | "verification-changed" | "interrupted" | "completed" | "failed" | "cancelled" | "closure-decided" | "continuation-started" | "closure-recorded";
+export interface PetLongTaskEvent {
+    id: string;
+    sequence: number;
+    kind: PetLongTaskEventKind;
+    at: number;
+    message?: string;
+    phase?: PetLongTaskPhase;
+    waitingFor?: string;
+    nextAction?: string;
+    artifacts?: PetLongTaskArtifact[];
+}
+export interface PetLongTask {
+    schemaVersion: typeof PET_LONG_TASK_SCHEMA_VERSION;
+    id: string;
+    originClientMessageId: string;
+    objective: string;
+    workspacePath: string | null;
+    sessionId: string;
+    /** Explicit external execution backend, when the user required one. */
+    executionBackend?: PetWorkExecutionBackend;
+    /** Ordinary final response, or persistent Goal verdict, required for closure. */
+    verificationMode: PetLongTaskVerificationMode;
+    completionTarget?: PetLongTaskCompletionTarget;
+    /** Number of terminal-result decisions Mimi has autonomously continued. */
+    continuationDepth?: number;
+    status: PetLongTaskStatus;
+    phase: PetLongTaskPhase;
+    attempt: number;
+    revision: number;
+    createdAt: number;
+    updatedAt: number;
+    startedAt?: number;
+    completedAt?: number;
+    /** The current attempt's terminal outcome reached durable Pet work memory. */
+    closureRecordedAt?: number;
+    /** Durable Mimi closure decision, persisted before any continuation side effect. */
+    closureDecision?: PetLongTaskClosureDecision;
+    /** Latest assistant-authored result/checkpoint, kept separate from UI progress text. */
+    resultSummary?: string;
+    summary?: string;
+    waitingFor?: string;
+    nextAction?: string;
+    lastError?: string;
+    artifacts: PetLongTaskArtifact[];
+    events: PetLongTaskEvent[];
+}
+export interface PetLongTaskContinuationDecision {
+    clientMessageId: string;
+    objective: string;
+    workspacePath: string | null;
+    executionBackend?: PetWorkExecutionBackend;
+}
+export interface PetLongTaskClosureDecision {
+    key: string;
+    text: string;
+    decidedAt: number;
+    /** Explicit GatewayReply attachment intent from Mimi's closure turn. */
+    replyAttachmentPaths?: string[];
+    /** Optional GatewayReply URL action, persisted for idempotent replay. */
+    replyButton?: {
+        text: string;
+        url: string;
+    };
+    continuation?: PetLongTaskContinuationDecision;
+    launch?: {
+        sessionId: string;
+        taskId?: string;
+        at: number;
+    };
+}
+export interface PetLongTaskSnapshot {
+    revision: number;
+    observedAt: number;
+    tasks: PetLongTask[];
+}
+export type PetLongTaskControlAction = "pause" | "resume" | "retry" | "cancel";
+export interface PetLongTaskControlRequest {
+    taskId: string;
+    action: PetLongTaskControlAction;
+}
+export type PetLongTaskControlResult = {
+    ok: true;
+    task: PetLongTask;
+} | {
+    ok: false;
+    code: "not-found" | "invalid-state" | "worker-error";
+    message: string;
+};
+export interface CreatePetLongTaskInput {
+    id: string;
+    originClientMessageId: string;
+    objective: string;
+    workspacePath: string | null;
+    sessionId: string;
+    executionBackend?: PetWorkExecutionBackend;
+    verificationMode?: PetLongTaskVerificationMode;
+    completionTarget?: PetLongTaskCompletionTarget;
+    continuationDepth?: number;
+    at: number;
+}
+export type PetLongTaskTransition = {
+    kind: "started";
+    at: number;
+    message?: string;
+} | {
+    kind: "progress";
+    at: number;
+    phase: PetLongTaskPhase;
+    summary: string;
+} | {
+    kind: "waiting";
+    at: number;
+    waitingFor: string;
+    message?: string;
+} | {
+    kind: "paused";
+    at: number;
+    reason?: string;
+} | {
+    kind: "resumed";
+    at: number;
+    message?: string;
+} | {
+    kind: "retrying";
+    at: number;
+    reason?: string;
+} | {
+    kind: "artifact";
+    at: number;
+    artifacts: PetLongTaskArtifact[];
+} | {
+    kind: "checkpoint";
+    at: number;
+    summary: string;
+    nextAction?: string;
+    artifacts?: PetLongTaskArtifact[];
+} | {
+    kind: "verification-changed";
+    at: number;
+    mode: PetLongTaskVerificationMode;
+} | {
+    kind: "interrupted";
+    at: number;
+    reason: string;
+} | {
+    kind: "completed";
+    at: number;
+    summary?: string;
+    artifacts?: PetLongTaskArtifact[];
+} | {
+    kind: "failed";
+    at: number;
+    error: string;
+    summary?: string;
+} | {
+    kind: "cancelled";
+    at: number;
+    reason?: string;
+} | {
+    kind: "closure-decided";
+    at: number;
+    key: string;
+    text: string;
+    replyAttachmentPaths?: string[];
+    replyButton?: {
+        text: string;
+        url: string;
+    };
+    continuation?: PetLongTaskContinuationDecision;
+} | {
+    kind: "continuation-started";
+    at: number;
+    key: string;
+    sessionId: string;
+    taskId?: string;
+} | {
+    kind: "closure-recorded";
+    at: number;
+};
+export declare function createPetLongTask(input: CreatePetLongTaskInput): PetLongTask;
+/**
+ * Apply one durable transition. Terminal tasks only accept retry/cancel or a
+ * closure-delivery acknowledgement; late
+ * worker events are ignored so a stale completion cannot undo an explicit user
+ * action such as pause or cancel.
+ */
+export declare function transitionPetLongTask(current: PetLongTask, transition: PetLongTaskTransition): PetLongTask;
+/** Defensive parser used by durable hosts. Invalid rows are dropped independently. */
+export declare function parsePetLongTask(value: unknown): PetLongTask | null;
+export interface PetLongTaskContext {
+    version: 1;
+    active: Array<{
+        taskId: string;
+        objective: string;
+        status: PetLongTaskStatus;
+        phase: PetLongTaskPhase;
+        sessionId: string;
+        workspace?: string;
+        attempt: number;
+        updatedAt: number;
+        summary?: string;
+        waitingFor?: string;
+        nextAction?: string;
+    }>;
+    recent: Array<{
+        taskId: string;
+        objective: string;
+        status: "completed" | "failed" | "cancelled";
+        sessionId: string;
+        workspace?: string;
+        updatedAt: number;
+        summary?: string;
+        artifacts?: PetLongTaskArtifact[];
+    }>;
+}
+/** Bounded task continuity injected into each Mimi manager turn. */
+export declare function buildPetLongTaskContext(tasks: readonly PetLongTask[]): PetLongTaskContext;
+export declare function petLongTaskResumePrompt(task: PetLongTask): string;