@markusylisiurunen/tau 0.3.34 → 0.3.35

package/dist/host/local_session_host.js

@@ -2,16 +2,18 @@ import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { resolvePromptTemplateWithBackend } from "../core/config/index.js";
 import { ChatRuntime } from "../core/runtime/chat_runtime.js";
+import { formatSteeringUserMessage } from "../core/runtime/steering.js";
+import { buildGoalContinuationText, prependGoalPolicy } from "../core/session/goal.js";
 import { SUBAGENT_ACTIVITY_FACET_KIND } from "../core/subagents/types.js";
 import { appendUsageLogEntry, getUsageCostTotal, getUsageTotals, } from "../core/usage/logs.js";
 import { filterProjectPathAutocompleteEntries, loadProjectPathAutocompleteEntriesWithBackend, } from "../core/utils/project_files.js";
-import { hasAutoCompactionContinuationMetadata, isTauUserMessageHidden, } from "../core/utils/user_metadata.js";
+import { hasAutoCompactionContinuationMetadata, hasGoalTurnMetadata, isTauUserMessageHidden, } from "../core/utils/user_metadata.js";
 import { applySessionProtocolDelta, createSessionProtocolDeltaMessage, createSessionProtocolEphemeralMessage, } from "../protocol/session_protocol.js";
 import { LEGACY_SESSION_CONTEXT_EPOCH } from "../store/session_snapshot_migrations.js";
 import { ClientToolBroker } from "./client_tool_broker.js";
 import { createExecutionEnvironmentSubagentRuntimeResolver } from "./execution_runtime.js";
 import { HostedEphemeralAgentSession } from "./hosted_ephemeral_agent_session.js";
-import { SessionExecBusyError, } from "./session_host.js";
+import { SessionExecBusyError, SessionRetryUnavailableError, } from "./session_host.js";
 const PATH_AUTOCOMPLETE_CACHE_TTL_MS = 5_000;
 export class LocalSessionHost {
     sessions = new Set();
@@ -124,6 +126,11 @@ export class LocalSessionHost {
             environment: this.sessionOptions.environment,
             eventSink: async (event) => await hostedSession.enqueueRuntimeEvent(event),
             subagentEventSink: async (event) => await hostedSession.recordSubagentEvent(event),
+            goalManager: {
+                getGoal: () => hostedSession.getGoal(),
+                createGoal: async (objective) => await hostedSession.createGoal(objective),
+                updateGoal: async (update) => await hostedSession.updateGoal(update),
+            },
             initialPromptComposition: committedSnapshot
                 ? promptCompositionFromSnapshot(committedSnapshot)
                 : undefined,
@@ -347,9 +354,12 @@ class LocalHostedSessionHandle {
     activeWorkPromises = new Set();
     activeExecAbortControllers = new Map();
     activeTurnPromise;
+    activeLogicalTurn;
     disposePromise;
     disposing = false;
     costTotal = 0;
+    goal;
+    pendingGoalCommit;
     forceNextSnapshotRevision;
     disposed = false;
     constructor(runtime, promptBootstrap, catalog, bootstrap, includeAgentContext, executionEnvironment, store, committedSnapshot, forceNextSnapshotRevision, recordUsage, removeFromHost = () => { }) {
@@ -370,12 +380,17 @@ class LocalHostedSessionHandle {
         this.persistedSnapshot = committedSnapshot
             ? cloneSessionProtocolSnapshot(committedSnapshot)
             : undefined;
+        this.goal = structuredClone(committedSnapshot?.goal ?? null);
         this.forceNextSnapshotRevision = forceNextSnapshotRevision;
         this.restoreProtocolState(committedSnapshot);
     }
     get isTurnRunning() {
         return this.runtime.isTurnRunning;
     }
+    get canAcceptSteering() {
+        return (this.runtime.isTurnRunning ||
+            Boolean(this.activeLogicalTurn && this.goal?.status === "active"));
+    }
     get sessionId() {
         return this.session.sessionId;
     }
@@ -397,6 +412,105 @@ class LocalHostedSessionHandle {
             this.ephemeralListeners.delete(handler);
         };
     }
+    getGoal() {
+        return structuredClone(this.goal);
+    }
+    async createGoal(objective) {
+        const goal = this.buildNewGoal(objective);
+        await this.setGoal(goal);
+        return structuredClone(goal);
+    }
+    async updateGoal(update) {
+        this.assertActive();
+        const current = this.goal;
+        if (!current) {
+            throw new Error("no goal exists");
+        }
+        if (update.objective !== undefined && update.status === "complete") {
+            throw new Error("goal objective cannot be updated while completing the goal");
+        }
+        if (update.status === "complete") {
+            await this.setGoal(null);
+            return null;
+        }
+        const objective = update.objective?.trim() ?? current.objective;
+        if (!objective) {
+            throw new Error("goal objective must not be empty");
+        }
+        const goal = {
+            objective,
+            status: update.status ?? current.status,
+        };
+        await this.setGoal(goal);
+        return structuredClone(goal);
+    }
+    async startGoal(objective) {
+        const goal = this.buildNewGoal(objective);
+        return await this.runLogicalTurn(async (logicalTurn) => {
+            this.goal = goal;
+            this.pendingGoalCommit = goal;
+            try {
+                const { userHistoryEntryId } = await this.record({
+                    text: prependGoalPolicy(goal.objective, goal),
+                });
+                if (logicalTurn.cancellationRequested) {
+                    return {
+                        userHistoryEntryId,
+                        turn: await this.cancelLogicalTurn(userHistoryEntryId),
+                    };
+                }
+                return {
+                    userHistoryEntryId,
+                    turn: await this.runTurnNow(logicalTurn, userHistoryEntryId),
+                };
+            }
+            catch (error) {
+                if (this.pendingGoalCommit === goal) {
+                    this.goal = null;
+                    this.pendingGoalCommit = undefined;
+                }
+                else {
+                    await this.blockActiveGoal().catch(() => undefined);
+                }
+                throw error;
+            }
+        });
+    }
+    async resumeGoal() {
+        this.assertActive();
+        if (this.goal?.status !== "blocked") {
+            throw new Error(this.goal ? "goal is already active" : "no goal exists");
+        }
+        const goal = { ...this.goal, status: "active" };
+        return await this.runLogicalTurn(async (logicalTurn) => {
+            await this.setGoal(goal);
+            try {
+                if (logicalTurn.cancellationRequested) {
+                    await this.blockActiveGoal();
+                    return { turn: abortedTurnOutcome() };
+                }
+                const { userHistoryEntryId } = await this.record({
+                    text: buildGoalContinuationText(goal),
+                });
+                if (logicalTurn.cancellationRequested) {
+                    return { turn: await this.cancelLogicalTurn(userHistoryEntryId) };
+                }
+                return { turn: await this.runTurnNow(logicalTurn, userHistoryEntryId) };
+            }
+            catch (error) {
+                await this.blockActiveGoal().catch(() => undefined);
+                throw error;
+            }
+        });
+    }
+    async clearGoal() {
+        this.assertActive();
+        if (!this.goal) {
+            throw new Error("no goal exists");
+        }
+        await this.setGoal(null);
+        return await this.snapshot();
+    }
     async record(options) {
         this.assertActive();
         const userHistoryEntryId = await this.session.commitUserText(options.text, options.historyEntryId ? { historyEntryId: options.historyEntryId } : undefined);
@@ -406,51 +520,118 @@ class LocalHostedSessionHandle {
         };
     }
     async runTurn() {
+        return await this.runLogicalTurn((logicalTurn) => this.runTurnNow(logicalTurn));
+    }
+    async retryTurn() {
+        const userMessage = this.session.rawHistoryEntries.findLast((entry) => entry.message.role === "user");
+        if (userMessage && hasGoalTurnMetadata(userMessage.message)) {
+            throw new SessionRetryUnavailableError("goal-controlled turns cannot be retried; resume a blocked goal or start a new goal");
+        }
+        return await this.runTurn();
+    }
+    async runLogicalTurn(execute) {
         this.assertActive();
-        const run = this.runTurnNow();
+        if (this.activeLogicalTurn) {
+            throw new Error("session turn is already active");
+        }
+        const logicalTurn = {
+            cancellationRequested: false,
+            pendingSteering: [],
+        };
+        this.activeLogicalTurn = logicalTurn;
+        const run = execute(logicalTurn);
         this.activeTurnPromise = run;
         try {
             return await run;
         }
         finally {
             if (this.activeTurnPromise === run) {
+                this.rejectBufferedLogicalSteering(logicalTurn, new Error("steering was not applied before the logical turn ended"));
                 this.activeTurnPromise = undefined;
+                this.activeLogicalTurn = undefined;
+                await this.emitSnapshotResetIfChanged("assistant-message");
             }
         }
     }
-    async runTurnNow() {
-        const userMessage = this.session.rawHistoryEntries.findLast((entry) => entry.message.role === "user");
-        if (!userMessage) {
+    async runTurnNow(logicalTurn, rootHistoryEntryId) {
+        const rootUserMessage = rootHistoryEntryId
+            ? this.session.rawHistoryEntries.find((entry) => entry.id === rootHistoryEntryId && entry.message.role === "user")
+            : this.session.rawHistoryEntries.findLast((entry) => entry.message.role === "user");
+        if (!rootUserMessage) {
             throw new Error("cannot run a turn without a user message");
         }
-        let lastAssistantMessage;
-        try {
-            const result = await this.runtime.runTurn();
-            lastAssistantMessage = result.finalMessage;
-            if (result.aborted && this.draftAssistantMessage) {
-                await this.interruptDraftAssistantMessage();
+        let goalRootHistoryEntryId = this.goal?.status === "active" ? rootUserMessage.id : undefined;
+        while (true) {
+            if (logicalTurn.cancellationRequested) {
+                return await this.cancelLogicalTurn(rootUserMessage.id);
             }
-            const outcome = turnOutcomeFromResult(result, lastAssistantMessage);
-            this.turnOutcomes.set(userMessage.id, outcome);
-            await this.emitSnapshotResetIfChanged("assistant-message");
-            return outcome;
-        }
-        catch (error) {
+            const committedSteering = [];
             try {
-                await this.cleanupFailedTurn();
+                while (logicalTurn.pendingSteering.length > 0) {
+                    committedSteering.push(await this.commitBufferedLogicalSteering(logicalTurn));
+                }
+                if (logicalTurn.cancellationRequested) {
+                    return await this.cancelLogicalTurn(rootUserMessage.id, committedSteering);
+                }
+                const userMessage = this.session.rawHistoryEntries.findLast((entry) => entry.message.role === "user");
+                if (!userMessage) {
+                    throw new Error("cannot run a turn without a user message");
+                }
+                const result = await this.runtime.runTurn();
+                const terminalResult = result.terminalResult;
+                if (terminalResult.aborted && this.draftAssistantMessage) {
+                    await this.interruptDraftAssistantMessage();
+                }
+                const initialOutcome = turnOutcomeFromResult(result, result.finalMessage);
+                const terminalOutcome = turnOutcomeFromResult(terminalResult, terminalResult.finalMessage);
+                this.turnOutcomes.set(userMessage.id, initialOutcome);
+                for (const steering of committedSteering) {
+                    this.turnOutcomes.set(steering.historyEntryId, initialOutcome);
+                }
+                if (this.goal?.status === "active") {
+                    goalRootHistoryEntryId ??= rootUserMessage.id;
+                }
+                if (goalRootHistoryEntryId) {
+                    this.turnOutcomes.set(goalRootHistoryEntryId, terminalOutcome);
+                }
+                if (terminalOutcome.status !== "completed") {
+                    await this.blockActiveGoal();
+                }
+                await this.emitSnapshotResetIfChanged("assistant-message");
+                this.resolveCommittedLogicalSteering(committedSteering, initialOutcome);
+                if (logicalTurn.cancellationRequested) {
+                    return await this.cancelLogicalTurn(rootUserMessage.id);
+                }
+                if (terminalOutcome.status !== "completed" || this.goal?.status !== "active") {
+                    return goalRootHistoryEntryId ? terminalOutcome : initialOutcome;
+                }
+                if (logicalTurn.pendingSteering.length > 0) {
+                    continue;
+                }
+                await this.session.commitUserText(buildGoalContinuationText(this.goal));
             }
-            catch {
-                // Preserve the original turn failure for the protocol response.
+            catch (error) {
+                this.rejectCommittedLogicalSteering(committedSteering, error);
+                await this.cleanupFailedTurn().catch(() => undefined);
+                await this.blockActiveGoal().catch(() => undefined);
+                throw error;
             }
-            throw error;
         }
     }
     interruptTurn() {
         this.assertActive();
-        return this.runtime.interruptTurn();
+        const logicalTurn = this.activeLogicalTurn;
+        if (logicalTurn) {
+            logicalTurn.cancellationRequested = true;
+        }
+        return this.runtime.interruptTurn() || Boolean(logicalTurn);
     }
     interruptActiveWork() {
-        let interrupted = this.runtime.interruptTurn();
+        const logicalTurn = this.activeLogicalTurn;
+        if (logicalTurn) {
+            logicalTurn.cancellationRequested = true;
+        }
+        let interrupted = this.runtime.interruptTurn() || Boolean(logicalTurn);
         for (const abortController of this.activeWorkAbortControllers) {
             if (!abortController.signal.aborted) {
                 abortController.abort();
@@ -476,30 +657,43 @@ class LocalHostedSessionHandle {
     }
     steer(text) {
         this.assertActive();
-        if (!this.activeTurnPromise) {
+        if (this.runtime.isTurnRunning) {
+            const submission = this.runtime.steer(text);
+            return {
+                id: submission.id,
+                applied: submission.applied.then((association) => ({
+                    userHistoryEntryId: association.historyEntryId,
+                })),
+                result: submission.result.then(async (association) => {
+                    const turn = turnOutcomeFromResult(association.result, association.result.finalMessage);
+                    await this.commitSteeringTurnOutcome(association.historyEntryId, turn);
+                    return {
+                        userHistoryEntryId: association.historyEntryId,
+                        turn,
+                    };
+                }),
+            };
+        }
+        const logicalTurn = this.activeLogicalTurn;
+        if (!logicalTurn || this.goal?.status !== "active") {
             throw new Error("cannot steer without an active turn");
         }
-        const submission = this.runtime.steer(text);
-        return {
-            id: submission.id,
-            applied: submission.applied.then(async (association) => {
-                await this.commitSnapshot();
-                return { userHistoryEntryId: association.historyEntryId };
-            }),
-            result: submission.result.then(async (association) => {
-                const turn = turnOutcomeFromResult(association.result, association.result.finalMessage);
-                this.turnOutcomes.set(association.historyEntryId, turn);
-                await this.emitSnapshotResetIfChanged("assistant-message");
-                return {
-                    userHistoryEntryId: association.historyEntryId,
-                    turn,
-                };
-            }),
-        };
+        return this.bufferLogicalSteering(logicalTurn, text);
     }
     cancelSteering() {
         this.assertActive();
-        return this.runtime.cancelSteering();
+        const cancelled = this.runtime.cancelSteering();
+        const logicalTurn = this.activeLogicalTurn;
+        if (!logicalTurn) {
+            return cancelled;
+        }
+        const buffered = logicalTurn.pendingSteering.splice(0);
+        const error = new Error("steering submission was cancelled");
+        for (const submission of buffered) {
+            submission.rejectApplied(error);
+            submission.rejectResult(error);
+        }
+        return [...cancelled, ...buffered.map(({ id, text }) => ({ id, text }))];
     }
     async exec(options) {
         return await this.runExec(options.execId, options.signal, async (signal) => {
@@ -875,6 +1069,120 @@ class LocalHostedSessionHandle {
             throw new AggregateError(errors, "failed to dispose hosted session");
         }
     }
+    buildNewGoal(objective) {
+        this.assertActive();
+        if (this.goal) {
+            throw new Error("a goal already exists; clear it before creating another");
+        }
+        const normalized = objective.trim();
+        if (!normalized) {
+            throw new Error("goal objective must not be empty");
+        }
+        return { objective: normalized, status: "active" };
+    }
+    async setGoal(goal) {
+        const previousGoal = structuredClone(this.goal);
+        this.goal = structuredClone(goal);
+        try {
+            await this.emitPatch("goal", [{ type: "goal.set", goal: structuredClone(goal) }]);
+        }
+        catch (error) {
+            this.goal = previousGoal;
+            throw error;
+        }
+    }
+    async blockActiveGoal() {
+        if (this.goal?.status === "active") {
+            await this.setGoal({ ...this.goal, status: "blocked" });
+        }
+    }
+    bufferLogicalSteering(logicalTurn, text) {
+        const normalized = text.trim();
+        if (!normalized) {
+            throw new Error("steering input must not be empty");
+        }
+        let resolveApplied;
+        let rejectApplied;
+        const applied = new Promise((resolve, reject) => {
+            resolveApplied = resolve;
+            rejectApplied = reject;
+        });
+        let resolveResult;
+        let rejectResult;
+        const result = new Promise((resolve, reject) => {
+            resolveResult = resolve;
+            rejectResult = reject;
+        });
+        const submission = {
+            id: `logical-steering-${randomUUID()}`,
+            text: normalized,
+            applied,
+            result,
+            resolveApplied,
+            resolveResult,
+            rejectApplied,
+            rejectResult,
+        };
+        logicalTurn.pendingSteering.push(submission);
+        return { id: submission.id, applied, result };
+    }
+    async commitBufferedLogicalSteering(logicalTurn) {
+        const submissions = logicalTurn.pendingSteering.splice(0);
+        if (submissions.length === 0) {
+            throw new Error("cannot commit empty logical steering");
+        }
+        try {
+            const goal = this.goal;
+            if (goal?.status !== "active") {
+                throw new Error("cannot commit logical steering without an active goal");
+            }
+            const historyEntryId = await this.session.commitUserText(prependGoalPolicy(formatSteeringUserMessage(submissions.map((submission) => submission.text)), goal));
+            for (const submission of submissions) {
+                submission.resolveApplied({ userHistoryEntryId: historyEntryId });
+            }
+            return { historyEntryId, submissions };
+        }
+        catch (error) {
+            const steeringError = error instanceof Error ? error : new Error(String(error));
+            for (const submission of submissions) {
+                submission.rejectApplied(steeringError);
+                submission.rejectResult(steeringError);
+            }
+            throw error;
+        }
+    }
+    resolveCommittedLogicalSteering(committed, turn) {
+        for (const { historyEntryId, submissions } of committed) {
+            for (const submission of submissions) {
+                submission.resolveResult({ userHistoryEntryId: historyEntryId, turn });
+            }
+        }
+    }
+    rejectCommittedLogicalSteering(committed, error) {
+        const steeringError = error instanceof Error ? error : new Error(String(error));
+        for (const { submissions } of committed) {
+            for (const submission of submissions) {
+                submission.rejectResult(steeringError);
+            }
+        }
+    }
+    rejectBufferedLogicalSteering(logicalTurn, error) {
+        for (const submission of logicalTurn.pendingSteering.splice(0)) {
+            submission.rejectApplied(error);
+            submission.rejectResult(error);
+        }
+    }
+    async cancelLogicalTurn(rootHistoryEntryId, committedSteering = []) {
+        const outcome = abortedTurnOutcome();
+        this.turnOutcomes.set(rootHistoryEntryId, outcome);
+        for (const steering of committedSteering) {
+            this.turnOutcomes.set(steering.historyEntryId, outcome);
+        }
+        await this.blockActiveGoal();
+        await this.emitSnapshotResetIfChanged("assistant-message");
+        this.resolveCommittedLogicalSteering(committedSteering, outcome);
+        return outcome;
+    }
     async commitSnapshot() {
         const write = this.snapshotQueue.catch(() => undefined).then(() => this.writeSnapshot());
         this.snapshotQueue = write.catch(() => undefined);
@@ -1024,7 +1332,8 @@ class LocalHostedSessionHandle {
                     ? { usageCheckpoint: { ...agentState.usageCheckpoint } }
                     : {}),
             },
-            lifecycle: this.runtime.isTurnRunning ? "running" : "idle",
+            lifecycle: this.activeTurnPromise || this.runtime.isTurnRunning ? "running" : "idle",
+            goal: structuredClone(this.goal),
             costTotal: this.costTotal,
             settings: {
                 personaId: this.runtime.persona.id,
@@ -1178,6 +1487,28 @@ class LocalHostedSessionHandle {
         this.runtimeEventQueue = write.catch(() => undefined);
         return write;
     }
+    async commitSteeringTurnOutcome(historyEntryId, turn) {
+        const write = this.runtimeEventQueue
+            .catch(() => undefined)
+            .then(async () => {
+            this.turnOutcomes.set(historyEntryId, turn);
+            const message = this.committedSnapshot?.messages.find((candidate) => candidate.id === historyEntryId);
+            if (!message) {
+                throw new Error(`missing steering user message '${historyEntryId}'`);
+            }
+            if (isDeepStrictEqual(message.turn, turn)) {
+                return;
+            }
+            await this.emitPatch("assistant-message", [
+                {
+                    type: "message.replace",
+                    message: { ...structuredClone(message), turn },
+                },
+            ]);
+        });
+        this.runtimeEventQueue = write.catch(() => undefined);
+        await write;
+    }
     removeToolRun(tool, changes) {
         this.tools.delete(tool.id);
         for (const facetId of tool.facetIds) {
@@ -1310,9 +1641,13 @@ class LocalHostedSessionHandle {
                 });
                 return;
             }
-            case "user_message":
+            case "user_message": {
+                const pendingGoal = this.pendingGoalCommit;
                 await this.emitPatch("user-message", [
                     this.agentStateChange(),
+                    ...(pendingGoal
+                        ? [{ type: "goal.set", goal: structuredClone(pendingGoal) }]
+                        : []),
                     {
                         type: "message.append",
                         message: {
@@ -1324,7 +1659,11 @@ class LocalHostedSessionHandle {
                         timelineItem: timelineItemForMessage(event.historyEntryId),
                     },
                 ], { persist: true });
+                if (pendingGoal && this.pendingGoalCommit === pendingGoal) {
+                    this.pendingGoalCommit = undefined;
+                }
                 return;
+            }
             case "history_rewound":
                 this.reconcileProjections({ removeMissingAgents: true });
                 await this.emitSnapshotResetIfChanged("maintenance");
@@ -1718,6 +2057,9 @@ class LocalHostedSessionHandle {
         await this.emitSnapshotResetIfChanged("assistant-message");
     }
 }
+function abortedTurnOutcome() {
+    return { status: "aborted", stopReason: "aborted" };
+}
 function turnOutcomeFromResult(result, assistantMessage) {
     if (result.blocked) {
         return { status: "blocked", ...result.blocked };
@@ -1806,6 +2148,10 @@ function normalizeRecoveredSnapshot(snapshot) {
     const legacyAgentState = recovered.agentState.contextEpoch === LEGACY_SESSION_CONTEXT_EPOCH;
     let changed = recovered.lifecycle !== "idle" || legacyAgentState;
     recovered.lifecycle = "idle";
+    if (recovered.goal?.status === "active") {
+        changed = true;
+        recovered.goal.status = "blocked";
+    }
     if (Object.keys(recovered.agents).length > 0) {
         changed = true;
         recovered.agents = {};