@evandu/super-pi 0.1.145 → 0.1.147

package/dist/server/application/session-orchestrator-service.d.ts

@@ -4,15 +4,30 @@ import type { RunService } from "./run-service.js";
 import type { SessionLedger } from "../session-ledger.js";
 import type { EventBroadcaster } from "../server-context.js";
 import type { RunStatus } from "../types.js";
+import { SessionWatchdog } from "./session-watchdog.js";
 export declare const SESSION_OUTPUT_CHAR_LIMIT: number;
 export declare const sessionResultRelativePath: (conversationId: string) => string;
+/**
+ * HOW MANY TIMES A CHILD MAY BE TOLD TO CONTINUE AFTER ITS OUTPUT WAS TRUNCATED.
+ *
+ * The bound is not about tokens - it is about a model that truncates on EVERY response. Three
+ * continuations cover the ordinary case (a long answer split across a few responses) and stop the
+ * pathological one. Past the bound the child is reported as unfinished, which is a true sentence
+ * about what happened, instead of a loop that never ends.
+ */
+export declare const MAX_LENGTH_CONTINUATIONS = 3;
 export interface SpawnSessionOptions {
     /** The high-level task to be performed by the sibling session. */
     task: string;
     /** Parent conversation initiating the orchestration, if any. */
     parentConversationId?: string;
-    /** Workspace ID for the new session. Inherited from parent if omitted. */
-    workspaceId?: string;
+    /** Explicit target workspace. A parent conversation records only the session-tree relationship. */
+    workspaceId: string;
+    /**
+     * Optional workspace-root-relative subdirectory for the new session. Invalid or out-of-bounds
+     * values are rejected before the conversation is created.
+     */
+    cwd?: string;
     /** Optional custom title for the new session. */
     title?: string;
     /** Optional agent override for the new session. */
@@ -28,6 +43,18 @@ export interface SpawnSessionOptions {
     initialPrompt?: string;
     /** Whether to await turn completion before returning (default: false, asynchronous dispatch). */
     wait?: boolean;
+    /** Optional silence watchdog timeout in seconds. If set, parent is reminded if child goes quiet for this duration. */
+    watchdogTimeoutSeconds?: number;
+}
+export interface ReportSessionOptions {
+    /** The report content (milestone, findings, roadblock, or final output). */
+    content: string;
+    /**
+     * The status of the child session when reporting.
+     * "in_progress" (default): interim update; resets the watchdog timer.
+     * "completed" | "failed": terminal update; cancels the watchdog timer.
+     */
+    status?: "in_progress" | "completed" | "failed";
 }
 export interface StopSessionOptions {
     /** Stop mode: "active" (active turn), "queued" (waiting messages in queue), or "all" (both, default). */
@@ -72,7 +99,35 @@ export declare class SessionOrchestratorService {
     private readonly runService;
     private readonly ledger;
     private readonly broadcaster?;
-    constructor(store: Store, conversationService: ConversationService, runService: RunService, ledger: SessionLedger, broadcaster?: EventBroadcaster | undefined);
+    readonly watchdog: SessionWatchdog;
+    /**
+     * HOW MANY TIMES EACH CHILD HAS BEEN TOLD TO CONTINUE AFTER A TRUNCATION.
+     *
+     * Per child rather than per dispatch, so a child that is given several tasks cannot extend itself
+     * indefinitely by being handed a new task each time it runs out of output budget. The entry is
+     * dropped as soon as the child finishes, so a child that continues successfully starts fresh on
+     * its next task.
+     */
+    private readonly lengthContinuations;
+    /**
+     * THE CHILDREN THAT HAVE ALREADY REPORTED THEIR OWN RESULT TO THEIR PARENT.
+     *
+     * A child can report explicitly - the `report` action - and that report is the child's own
+     * statement of what it did. When the child's turn then ends, the automatic completion report
+     * would deliver the same thing a second time, so the automatic path steps aside for a child that
+     * is in this set.
+     *
+     * The entry is added only by a TERMINAL report (`completed` / `failed`), because an interim
+     * update is not the child's final word: the task is still running, and the parent will want to
+     * hear how it ended.
+     */
+    private readonly reportedChildren;
+    constructor(store: Store, conversationService: ConversationService, runService: RunService, ledger: SessionLedger, broadcaster?: EventBroadcaster | undefined, watchdog?: SessionWatchdog);
+    /**
+     * The watchdog timer fired: the child has been silent for longer than the parent declared.
+     * Delivers a reminder message to the parent session. Does NOT interrupt or abort the child session.
+     */
+    private handleWatchdogTimeout;
     /**
      * Spawns a new sibling conversation and immediately dispatches its initial task.
      */
@@ -88,6 +143,58 @@ export declare class SessionOrchestratorService {
     }): Promise<{
         conversationId: string;
     }>;
+    /**
+     * THE CHILD'S OUTPUT WAS CUT OFF. TELL IT TO CARRY ON, AND LET IT.
+     *
+     * This is the recovery for a length stop, and it exists because a truncated answer is not a
+     * finished one. The child has already said most of what it had to say - that text is on its
+     * transcript - so the work left to do is the tail of the answer, not the whole of it.
+     *
+     * WHY THE CONTINUATION IS A NEW TURN RATHER THAN A RESUME OF THE SAME ONE. Pi has already settled
+     * the turn that was truncated: the model stopped, the message was written, the run ended. There is
+     * no live turn to resume, so the only way to get more output is to ask again - and asking again in
+     * the SAME conversation is what makes the continuation work, because the child's own partial
+     * answer is in its context and the model can see exactly where it stopped.
+     *
+     * WHY IT IS AN AGENT-SENT ORDER RATHER THAN A USER MESSAGE. The person never typed this, and the
+     * child's transcript must not show words under their name that they never said - the same reason
+     * `dispatch` uses `enqueueAndRunAsAgent` in the first place.
+     *
+     * Returns true when the child was continued (and the caller must NOT report a failure), and false
+     * when the continuation could not be made or the bound was reached - in which case the caller
+     * reports the original failure, which is then the honest description of what happened.
+     */
+    private continueAfterLengthStop;
+    /**
+     * Explicit report from a child session to its direct parent.
+     * Can be called multiple times at any point during execution.
+     */
+    report(childConversationId: string, options: ReportSessionOptions): Promise<{
+        delivered: boolean;
+        parentConversationId: string;
+    }>;
+    /**
+     * Sets or updates a silence watchdog timer on a child session.
+     */
+    setWatchdog(options: {
+        childConversationId: string;
+        parentConversationId: string;
+        timeoutSeconds: number;
+    }): Promise<{
+        ok: boolean;
+        childConversationId: string;
+        timeoutSeconds: number;
+    }>;
+    /**
+     * Cancels a silence watchdog timer on a child session.
+     */
+    cancelWatchdog(childConversationId: string): Promise<{
+        ok: boolean;
+    }>;
+    /**
+     * Re-arms persisted watchdogs from disk.
+     */
+    restoreWatchdogs(): Promise<void>;
     private persistSessionResult;
     /**
      * Returns a high-level summary of a session's progress without returning full transcripts.
@@ -98,6 +205,10 @@ export declare class SessionOrchestratorService {
     }): Promise<SessionSummary>;
     /**
      * Lists summaries of all sessions, optionally filtered by parent conversation.
+     *
+     * Persisted store conversations are the authoritative source for session tree
+     * parent-child relationships across server restarts, while SessionLedger
+     * enriches live in-memory task, progress, and activeTool state.
      */
     list(parentConversationId?: string): Promise<SessionSummary[]>;
     /**