@womp/spark-agent 6.4.0 → 7.0.0

package/dist/goals.d.ts

@@ -22,7 +22,7 @@ export type SparkGoalTry = {
     /** In the order of the goal's conditions; a condition left to the user has no result. */
     conditions: Pick<SparkGoalCondition, "met" | "reason">[];
 };
-/** The conditions read from a user message, for the user to confirm before a goal starts. */
+/** The goal the agent proposes for a request, for the user to confirm before it starts. */
 export declare const sparkGoalProposalSchema: z.ZodObject<{
     title: z.ZodString;
     conditions: z.ZodArray<z.ZodObject<{
@@ -31,6 +31,43 @@ export declare const sparkGoalProposalSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type SparkGoalProposal = z.infer<typeof sparkGoalProposalSchema>;
+/**
+ * How the user answered a proposed goal: run it with these caps, try the request
+ * once, or nothing in the time the host waits.
+ */
+export declare const sparkGoalDecisionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    creditBudget: z.ZodOptional<z.ZodNumber>;
+    maxTurns: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodLiteral<"goal">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"once">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"unanswered">;
+}, z.core.$strip>], "kind">;
+export type SparkGoalDecision = z.infer<typeof sparkGoalDecisionSchema>;
+/** What became of a proposal, as the agent is told: `active` when a goal was already running. */
+export declare const SPARK_GOAL_OUTCOMES: readonly ["started", "declined", "unanswered", "active"];
+export type SparkGoalOutcome = (typeof SPARK_GOAL_OUTCOMES)[number];
+/**
+ * A proposal as its message stores it: the `propose_goal` call that made it, and
+ * its outcome once there is one. Without an outcome it is waiting for the user
+ * while its run is, and was left unanswered once that run has ended.
+ */
+export declare const sparkGoalProposalPartSchema: z.ZodObject<{
+    title: z.ZodString;
+    conditions: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        measurable: z.ZodBoolean;
+    }, z.core.$strip>>;
+    toolCallId: z.ZodString;
+    outcome: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        unanswered: "unanswered";
+        started: "started";
+        declined: "declined";
+    }>>;
+}, z.core.$strip>;
+export type SparkGoalProposalPart = z.infer<typeof sparkGoalProposalPartSchema>;
 /** The caps a goal confirmation offers before the user changes them. */
 export declare const GOAL_CONFIRMATION_DEFAULTS: {
     readonly tries: 5;
@@ -61,20 +98,15 @@ export type SparkGoal = {
     runId?: string;
 };
 export declare const sparkGoalCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    creditBudget: z.ZodOptional<z.ZodNumber>;
+    maxTurns: z.ZodOptional<z.ZodNumber>;
     action: z.ZodLiteral<"set">;
     objective: z.ZodString;
-    title: z.ZodOptional<z.ZodString>;
-    conditions: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        text: z.ZodString;
-        measurable: z.ZodBoolean;
-    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
     creditBudget: z.ZodOptional<z.ZodNumber>;
     maxTurns: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodObject<{
     action: z.ZodLiteral<"update_budget">;
     goalId: z.ZodString;
-    creditBudget: z.ZodOptional<z.ZodNumber>;
-    maxTurns: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     action: z.ZodEnum<{
         status: "status";

package/dist/goals.js

@@ -11,10 +11,34 @@ export const sparkGoalConditionSchema = z.object({
      */
     measurable: z.boolean(),
 });
-/** The conditions read from a user message, for the user to confirm before a goal starts. */
+const goalCaps = {
+    creditBudget: z.number().int().positive().max(1_000_000_000).optional(),
+    maxTurns: z.number().int().min(1).max(100).optional(),
+};
+/** The goal the agent proposes for a request, for the user to confirm before it starts. */
 export const sparkGoalProposalSchema = z.object({
     title: z.string().trim().min(1).max(80),
-    conditions: z.array(sparkGoalConditionSchema).max(MAX_GOAL_CONDITIONS),
+    conditions: z.array(sparkGoalConditionSchema).min(1).max(MAX_GOAL_CONDITIONS),
+});
+/**
+ * How the user answered a proposed goal: run it with these caps, try the request
+ * once, or nothing in the time the host waits.
+ */
+export const sparkGoalDecisionSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("goal"), ...goalCaps }),
+    z.object({ kind: z.literal("once") }),
+    z.object({ kind: z.literal("unanswered") }),
+]);
+/** What became of a proposal, as the agent is told: `active` when a goal was already running. */
+export const SPARK_GOAL_OUTCOMES = ["started", "declined", "unanswered", "active"];
+/**
+ * A proposal as its message stores it: the `propose_goal` call that made it, and
+ * its outcome once there is one. Without an outcome it is waiting for the user
+ * while its run is, and was left unanswered once that run has ended.
+ */
+export const sparkGoalProposalPartSchema = sparkGoalProposalSchema.extend({
+    toolCallId: z.string().min(1),
+    outcome: z.enum(SPARK_GOAL_OUTCOMES).optional(),
 });
 /** The caps a goal confirmation offers before the user changes them. */
 export const GOAL_CONFIRMATION_DEFAULTS = { tries: 5, credits: 2_000 };
@@ -22,17 +46,13 @@ export const sparkGoalCommandSchema = z.discriminatedUnion("action", [
     z.object({
         action: z.literal("set"),
         objective: z.string().trim().min(1).max(MAX_GOAL_LENGTH),
-        title: sparkGoalProposalSchema.shape.title.optional(),
-        conditions: sparkGoalProposalSchema.shape.conditions.min(1).optional(),
-        creditBudget: z.number().int().positive().max(1_000_000_000).optional(),
-        maxTurns: z.number().int().min(1).max(100).optional(),
+        ...goalCaps,
     }),
     // Raises or lowers a goal's caps; at least one of them.
     z.object({
         action: z.literal("update_budget"),
         goalId: z.string().min(1),
-        creditBudget: z.number().int().positive().max(1_000_000_000).optional(),
-        maxTurns: z.number().int().min(1).max(100).optional(),
+        ...goalCaps,
     }),
     z.object({ action: z.enum(["status", "pause", "resume", "clear"]) }),
 ]);

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { runSparkAgent, type SparkAgentOptions, type SparkAgentResult, type SparkAgentRun, } from "./agent.js";
 export { createSparkTools, type SparkPersistence, type SparkToolCall } from "./agent-tools.js";
 export { convertSparkMessages } from "./model-history.js";
-export type { SparkCompactionLimits } from "./compaction.js";
-export * from "./context-budget.js";
+export { applyCompaction, latestCompaction, type SparkCompactionLimits } from "./compaction.js";
+export * from "./context-window.js";
 export * from "./capabilities.js";
 export { createSdkSceneEditor, createSdkSceneHost, type SdkSceneEditor, type SdkSceneEditorOptions, type SdkSceneEditIdentity, type SdkSceneServices, } from "./sdk-scene-host.js";
 export { recoverSceneOperation, type SceneOperation, type SceneOperationStore } from "./scene-operations.js";

package/dist/index.js

@@ -1,7 +1,8 @@
 export { runSparkAgent, } from "./agent.js";
 export { createSparkTools } from "./agent-tools.js";
 export { convertSparkMessages } from "./model-history.js";
-export * from "./context-budget.js";
+export { applyCompaction, latestCompaction } from "./compaction.js";
+export * from "./context-window.js";
 export * from "./capabilities.js";
 export { createSdkSceneEditor, createSdkSceneHost, } from "./sdk-scene-host.js";
 export { recoverSceneOperation } from "./scene-operations.js";

package/dist/model-history.js

@@ -23,16 +23,6 @@ async function liveInput(tools, part) {
     const validated = await asSchema(tool.inputSchema).validate?.(input);
     return validated?.success ? { ...part, input: validated.value } : part;
 }
-/** How the worker reads the conditions the user confirmed for the goal a message starts. */
-function goalConditionsText({ conditions }) {
-    const list = (measurable) => conditions.filter((condition) => condition.measurable === measurable).map(({ text }) => `\n- ${text}`).join("");
-    const measured = list(true);
-    const reviewed = list(false);
-    return "[The user confirmed this request as a goal. Keep working until it is met; do not ask whether to continue."
-        + (measured ? `\nConditions an independent check will verify. Verify each with concrete tool results before claiming completion:${measured}` : "")
-        + (reviewed ? `\nPreferences the user will review themselves:${reviewed}` : "")
-        + "]";
-}
 /**
  * The stored conversation as model messages. UI artifact previews already
  * represented by a tool result are not model output. The messages before the
@@ -70,10 +60,6 @@ export async function convertSparkMessages(messages, tools, options = {}) {
     return convertToModelMessages(history, {
         tools,
         convertDataPart: (part) => {
-            if (part.type === "data-goal") {
-                const goal = sparkDataPartSchemas.goal.safeParse(part.data);
-                return goal.success ? { type: "text", text: goalConditionsText(goal.data) } : undefined;
-            }
             if (part.type !== "data-selection")
                 return undefined;
             const selection = sparkDataPartSchemas.selection.safeParse(part.data);

package/dist/server/executor.js

@@ -15,6 +15,7 @@ export function createSparkRunExecutor(options) {
                 runId: context.runId,
                 messageId: context.assistantMessageId,
                 signal: context.signal,
+                proposeGoal: context.proposeGoal,
             });
             return { stream: run.stream, result: run.result.finally(() => host.dispose()) };
         }

package/dist/server/express.js

@@ -100,15 +100,6 @@ export function createSparkAgentRouter(options) {
         const result = await options.service.goalCommand(ownerId, request.params.conversationId, body.command, body.settings, body.message);
         response.status(result.run ? 202 : 200).json(result);
     });
-    router.post("/conversations/:conversationId/goal/proposal", async (request, response) => {
-        const ownerId = await resolveOwnerId(request);
-        const body = z.object({ message: messageSchema, settings: settingsSchema }).parse(request.body);
-        const abortController = new AbortController();
-        response.on("close", () => { if (!response.writableEnded)
-            abortController.abort(); });
-        const proposal = await options.service.proposeGoal(ownerId, request.params.conversationId, body.message, body.settings, abortController.signal);
-        response.json({ proposal });
-    });
     router.get("/conversations/:conversationId/active-run", async (request, response) => {
         const ownerId = await resolveOwnerId(request);
         const run = await options.service.getActiveRun(ownerId, request.params.conversationId);

package/dist/server/index.d.ts

@@ -1,8 +1,7 @@
 export { MemorySparkArtifactStore } from "./artifacts.js";
 export { WompifyCreditCapReachedError } from "../wompify.js";
 export { createSparkGoalEvaluator, GOAL_REFERENCE_IMAGES, type SparkGoalEvaluator, type SparkGoalEvaluation } from "./goal-evaluator.js";
-export { createSparkGoalProposer, type SparkGoalProposer } from "./goal-proposer.js";
-export { sparkGoalCommandSchema, sparkGoalProposalSchema, type SparkGoal, type SparkGoalCommand, type SparkGoalCondition, type SparkGoalProposal, type SparkGoalTry } from "../goals.js";
+export { sparkGoalCommandSchema, sparkGoalDecisionSchema, sparkGoalProposalSchema, type SparkGoal, type SparkGoalCommand, type SparkGoalCondition, type SparkGoalDecision, type SparkGoalProposal, type SparkGoalTry } from "../goals.js";
 export type { SparkArtifactStore, StoredSparkArtifact } from "./artifacts.js";
 export { createSparkRunExecutor, type ResolvedSparkModel, type SparkRunExecutorOptions, } from "./executor.js";
 export { DEFAULT_ENDING_RETRY_DELAYS_MS, RUN_INTERRUPTED_ERROR, RUN_NOT_SAVED_ERROR, SparkAgentService, SparkServiceError, } from "./service.js";

package/dist/server/index.js

@@ -1,8 +1,7 @@
 export { MemorySparkArtifactStore } from "./artifacts.js";
 export { WompifyCreditCapReachedError } from "../wompify.js";
 export { createSparkGoalEvaluator, GOAL_REFERENCE_IMAGES } from "./goal-evaluator.js";
-export { createSparkGoalProposer } from "./goal-proposer.js";
-export { sparkGoalCommandSchema, sparkGoalProposalSchema } from "../goals.js";
+export { sparkGoalCommandSchema, sparkGoalDecisionSchema, sparkGoalProposalSchema } from "../goals.js";
 export { createSparkRunExecutor, } from "./executor.js";
 export { DEFAULT_ENDING_RETRY_DELAYS_MS, RUN_INTERRUPTED_ERROR, RUN_NOT_SAVED_ERROR, SparkAgentService, SparkServiceError, } from "./service.js";
 export { MemorySparkAgentStore } from "./store.js";

package/dist/server/service.d.ts

@@ -1,7 +1,6 @@
 import { type SparkUIMessage, type StoredSparkChunk } from "../ui.js";
-import { type SparkGoal, type SparkGoalCommand, type SparkGoalProposal } from "../goals.js";
+import { type SparkGoal, type SparkGoalCommand, type SparkGoalDecision, type SparkGoalProposal } from "../goals.js";
 import { type SparkGoalEvaluator } from "./goal-evaluator.js";
-import type { SparkGoalProposer } from "./goal-proposer.js";
 import type { SparkAgentStore, SparkConversation, SparkConversationSummary, SparkRun, SparkRunExecutor, SparkRunSettings } from "./types.js";
 /** Why a run ended when its progress could not be stored. */
 export declare const RUN_NOT_SAVED_ERROR = "This run was stopped because its progress could not be saved.";
@@ -13,8 +12,25 @@ export type SparkAgentServiceOptions = {
     store: SparkAgentStore;
     executeRun: SparkRunExecutor;
     evaluateGoal?: SparkGoalEvaluator;
-    /** Reads a message's success conditions for the user to confirm before a goal starts. */
-    proposeGoal?: SparkGoalProposer;
+    /**
+     * Shows the user a goal the agent proposed and resolves their answer. With it
+     * and `evaluateGoal`, the agent has `propose_goal`; the run waits here, and a
+     * confirmed goal starts with that run as its first try.
+     */
+    confirmGoal?(input: {
+        ownerId: string;
+        conversationId: string;
+        runId: string;
+        toolCallId: string;
+        proposal: SparkGoalProposal;
+        signal: AbortSignal;
+    }): Promise<SparkGoalDecision>;
+    /** Called once a confirmed goal is stored and before the agent goes on, for a host that counts what a goal spends. A goal it refuses does not start. */
+    onGoalStart?(input: {
+        ownerId: string;
+        run: SparkRun;
+        goal: SparkGoal;
+    }): Promise<void>;
     /** Charged and pending credits, including evaluations; reject if unavailable. */
     readGoalCredits?(ownerId: string, goal: SparkGoal): Promise<number>;
     continuationSettings?(settings: SparkRunSettings): SparkRunSettings;
@@ -44,7 +60,8 @@ export declare class SparkAgentService {
     private readonly store;
     private readonly executeRun;
     private readonly evaluateGoal?;
-    private readonly proposer?;
+    private readonly confirmGoal?;
+    private readonly onGoalStart?;
     private readonly readGoalCredits?;
     private readonly continuationSettings?;
     private closing;
@@ -68,11 +85,6 @@ export declare class SparkAgentService {
     getConversation(ownerId: string, id: string): Promise<SparkConversation>;
     saveConversationSettings(ownerId: string, id: string, settings: SparkRunSettings): Promise<void>;
     deleteConversation(ownerId: string, id: string): Promise<void>;
-    /**
-     * The conditions a goal started from `message` would verify. Nothing is stored
-     * or started: the user confirms them, then sends the message with a `set` command.
-     */
-    proposeGoal(ownerId: string, conversationId: string, message: SparkUIMessage, settings: SparkRunSettings, signal?: AbortSignal): Promise<SparkGoalProposal>;
     /** User controls are separate from model execution and work while streaming. */
     goalCommand(ownerId: string, conversationId: string, command: SparkGoalCommand, settings?: SparkRunSettings, message?: SparkUIMessage): Promise<{
         goal?: SparkGoal;
@@ -97,6 +109,8 @@ export declare class SparkAgentService {
     cancelRun(ownerId: string, runId: string): Promise<SparkRun>;
     streamRun(ownerId: string, runId: string, afterSequence: number, signal: AbortSignal): AsyncGenerator<StoredSparkChunk>;
     private runInBackground;
+    /** Starts the goal the user confirmed, with the run that proposed it as its first try. */
+    private startGoal;
     private refreshGoalCredits;
     private pauseRunGoal;
     private advanceGoal;

package/dist/server/service.js

@@ -2,7 +2,7 @@ import { sparkErrorDiagnostics } from "../error-diagnostics.js";
 import { validateUIMessages } from "ai";
 import { foldAllChunks } from "./message-fold.js";
 import { sparkDataPartSchemas, sparkMessageMetadataSchema, } from "../ui.js";
-import { sparkGoalCommandSchema, sparkGoalProposalSchema } from "../goals.js";
+import { MAX_GOAL_LENGTH, sparkGoalCommandSchema, sparkGoalDecisionSchema } from "../goals.js";
 import { goalVerdictSchema } from "./goal-evaluator.js";
 import { wompifyContextSchema, WompifyCreditCapReachedError } from "../wompify.js";
 const TERMINAL_STATUSES = new Set([
@@ -52,14 +52,13 @@ function titleFor(message) {
         return "New build";
     return text.length > 44 ? `${text.slice(0, 44)}…` : text;
 }
-/** `confirmedGoal` admits the goal part, which only a `set` command attaches. */
-function normalizeUserMessage(message, confirmedGoal = false) {
+function normalizeUserMessage(message) {
     if (message.role !== "user") {
         throw new SparkServiceError(400, "A new chat message must have the user role.");
     }
     for (const part of message.parts) {
         // The data schemas are checked with the rest of the message (validateUIMessages).
-        if (part.type === "text" || part.type === "data-selection" || (confirmedGoal && part.type === "data-goal"))
+        if (part.type === "text" || part.type === "data-selection")
             continue;
         if (part.type === "file" &&
             part.mediaType.startsWith("image/") &&
@@ -107,7 +106,8 @@ export class SparkAgentService {
     store;
     executeRun;
     evaluateGoal;
-    proposer;
+    confirmGoal;
+    onGoalStart;
     readGoalCredits;
     continuationSettings;
     closing = false;
@@ -126,7 +126,8 @@ export class SparkAgentService {
         this.store = options.store;
         this.executeRun = options.executeRun;
         this.evaluateGoal = options.evaluateGoal;
-        this.proposer = options.proposeGoal;
+        this.confirmGoal = options.confirmGoal;
+        this.onGoalStart = options.onGoalStart;
         this.readGoalCredits = options.readGoalCredits;
         this.continuationSettings = options.continuationSettings;
         this.endOrphanedRuns = options.endOrphanedRuns ?? false;
@@ -167,21 +168,6 @@ export class SparkAgentService {
             }
         });
     }
-    /**
-     * The conditions a goal started from `message` would verify. Nothing is stored
-     * or started: the user confirms them, then sends the message with a `set` command.
-     */
-    async proposeGoal(ownerId, conversationId, message, settings, signal) {
-        if (!this.proposer)
-            throw new SparkServiceError(501, "This host has not configured goal proposals.");
-        const conversation = await this.getConversation(ownerId, conversationId);
-        const [input] = await validateUIMessages({ messages: [normalizeUserMessage(message)], metadataSchema: sparkMessageMetadataSchema, dataSchemas: sparkDataPartSchemas });
-        const timeout = AbortSignal.timeout(30_000);
-        return sparkGoalProposalSchema.parse(await this.proposer({
-            ownerId, message: input, messages: conversation.messages, settings,
-            signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
-        }));
-    }
     /** User controls are separate from model execution and work while streaming. */
     async goalCommand(ownerId, conversationId, command, settings, message) {
         command = sparkGoalCommandSchema.parse(command);
@@ -261,24 +247,19 @@ export class SparkAgentService {
                 throw new SparkServiceError(400, "Run settings are required.");
             const goal = command.action === "set" ? {
                 id: crypto.randomUUID(), objective: command.objective, status: "active",
-                ...(command.title ? { title: command.title } : {}),
-                ...(command.conditions ? { conditions: command.conditions } : {}),
                 settings: runSettings,
                 createdAt: now(), updatedAt: now(), turns: 0,
                 ...(command.maxTurns ? { maxTurns: command.maxTurns } : {}),
                 ...(command.creditBudget ? { creditBudget: command.creditBudget, creditsUsed: 0 } : {}),
             } : { ...current, settings: runSettings, status: "active", updatedAt: now(),
                 idleTurns: 0, };
-            // Only the confirmed command says what the goal's conditions are, not the message a client built.
-            const inputMessage = normalizeUserMessage(message ? { ...message, parts: message.parts.filter((part) => part.type !== "data-goal") } : {
+            const inputMessage = normalizeUserMessage(message ?? {
                 id: crypto.randomUUID(), role: "user", parts: [{ type: "text", text: goalStartText(goal, command.action) }],
             });
-            if (command.action === "set" && command.conditions)
-                inputMessage.parts.push({ type: "data-goal", data: { title: command.title ?? titleFor(inputMessage), conditions: command.conditions } });
             await validateUIMessages({ messages: [inputMessage], metadataSchema: sparkMessageMetadataSchema, dataSchemas: sparkDataPartSchemas });
             await this.store.saveConversationGoal(conversationId, goal);
             try {
-                const run = await this.submitInTurn({ ownerId, conversationId, trigger: "submit-message", message: inputMessage, settings: goal.settings }, command.action === "resume", true);
+                const run = await this.submitInTurn({ ownerId, conversationId, trigger: "submit-message", message: inputMessage, settings: goal.settings }, command.action === "resume");
                 return { goal: (await this.getConversation(ownerId, conversationId)).goal, run };
             }
             catch (error) {
@@ -342,7 +323,7 @@ export class SparkAgentService {
     async submitMessage(input) {
         return this.inConversationTurn(input.conversationId, () => this.submitInTurn(input));
     }
-    async submitInTurn(input, goalContinuation = false, confirmedGoal = false) {
+    async submitInTurn(input, goalContinuation = false) {
         if (this.closing)
             throw new SparkServiceError(503, "The service is shutting down.");
         const conversation = await this.getConversation(input.ownerId, input.conversationId);
@@ -370,7 +351,7 @@ export class SparkAgentService {
             inputMessage = previous;
         }
         else {
-            inputMessage = normalizeUserMessage(input.message, confirmedGoal);
+            inputMessage = normalizeUserMessage(input.message);
             if (goalContinuation)
                 inputMessage.metadata = { ...inputMessage.metadata, goalContinuation: true };
             if (conversation.messages.some(({ id }) => id === inputMessage.id)) {
@@ -548,6 +529,20 @@ export class SparkAgentService {
                 data: { runId: run.id, status: "running" },
             };
             await this.appendChunk(run, runningChunk);
+            const proposeGoal = this.confirmGoal && this.evaluateGoal && this.store.saveConversationGoal && (async (proposal, call) => {
+                if (run.goalId)
+                    return "active";
+                const decision = sparkGoalDecisionSchema.parse(await this.confirmGoal({
+                    ownerId: conversation.ownerId, conversationId: conversation.id, runId: run.id, toolCallId: call.toolCallId, proposal, signal: call.signal,
+                }));
+                if (decision.kind !== "goal")
+                    return decision.kind === "once" ? "declined" : "unanswered";
+                const started = await this.startGoal(run, proposal, decision);
+                if (!started)
+                    return "active";
+                run = started;
+                return "started";
+            });
             const execution = await this.executeRun({
                 ownerId: conversation.ownerId,
                 conversationId: conversation.id,
@@ -556,6 +551,7 @@ export class SparkAgentService {
                 uiMessages: conversation.messages,
                 settings: run.settings,
                 goal: conversation.goal?.status === "active" ? conversation.goal : undefined,
+                ...(proposeGoal ? { proposeGoal } : {}),
                 signal: AbortSignal.any([controller.signal, unsaved.signal]),
             });
             // A chunk that cannot be stored aborts the execution, and the stream is
@@ -627,6 +623,35 @@ export class SparkAgentService {
             this.controllers.delete(run.id);
         }
     }
+    /** Starts the goal the user confirmed, with the run that proposed it as its first try. */
+    async startGoal(run, proposal, caps) {
+        if (caps.creditBudget !== undefined && !this.readGoalCredits)
+            throw new SparkServiceError(501, "This host does not support credit budgets.");
+        return this.inConversationTurn(run.conversationId, async () => {
+            const conversation = await this.store.getConversation(run.conversationId);
+            if (!conversation || conversation.activeRunId !== run.id || conversation.goal?.status === "active")
+                return undefined;
+            const request = conversation.messages.find(({ id }) => id === run.inputMessageId);
+            const createdAt = now();
+            const goal = {
+                id: crypto.randomUUID(), objective: (request ? messageText(request) : "").slice(0, MAX_GOAL_LENGTH) || proposal.title, ...proposal,
+                status: "active", settings: run.settings, createdAt, updatedAt: createdAt, turns: 0, runId: run.id,
+                ...(caps.maxTurns ? { maxTurns: caps.maxTurns } : {}),
+                ...(caps.creditBudget ? { creditBudget: caps.creditBudget, creditsUsed: 0 } : {}),
+            };
+            const started = { ...run, goalId: goal.id };
+            await this.store.saveConversationGoal(conversation.id, goal);
+            try {
+                await this.onGoalStart?.({ ownerId: conversation.ownerId, run: started, goal });
+                await this.store.saveRun(started);
+            }
+            catch (error) {
+                await this.store.saveConversationGoal(conversation.id, conversation.goal);
+                throw error;
+            }
+            return started;
+        });
+    }
     async refreshGoalCredits(ownerId, goal) {
         if (goal.creditBudget === undefined)
             return goal;

package/dist/server/standalone.d.ts

@@ -1,6 +1,6 @@
 import { type Express } from "express";
 import { KakapoAPI } from "@womp/kakapo-sdk";
-import type { SparkGoal } from "../goals.js";
+import { type SparkGoal } from "../goals.js";
 import type { SparkAgentStore } from "./types.js";
 export type StandaloneSparkAgentOptions = {
     openAiApiKey?: string;

package/dist/server/standalone.js

@@ -19,7 +19,7 @@ import { QuickJSJavaScriptExecutor } from "../quickjs-executor.js";
 import { sparkModelOptions } from "../model-options.js";
 import { createSparkRunExecutor } from "./executor.js";
 import { createSparkGoalEvaluator } from "./goal-evaluator.js";
-import { createSparkGoalProposer } from "./goal-proposer.js";
+import { sparkGoalDecisionSchema } from "../goals.js";
 import { createSparkAgentRouter } from "./express.js";
 import { SparkAgentService } from "./service.js";
 import { SqliteSparkStore } from "./sqlite-store.js";
@@ -238,11 +238,16 @@ export async function createStandaloneSparkAgentApp(options) {
     }
     let clearingScene = false;
     let activeRuns = 0;
+    /** The goal proposals runs are waiting on, by the tool call that made them. */
+    const goalAnswers = new Map();
     const service = new SparkAgentService({
         store,
         evaluateGoal: createSparkGoalEvaluator({ resolveModel, resolveImage: (ownerId, artifactId) => artifactStore.get(ownerId, artifactId) }),
-        // Reading a request's conditions precedes every send, so it runs at the lowest effort.
-        proposeGoal: createSparkGoalProposer({ resolveModel: (settings) => resolveModel({ ...settings, reasoningEffort: "low" }) }),
+        // The run waits until the UI answers on the route below, or the run is stopped.
+        confirmGoal: ({ toolCallId, signal }) => new Promise((resolve, reject) => {
+            goalAnswers.set(toolCallId, resolve);
+            signal.addEventListener("abort", () => { goalAnswers.delete(toolCallId); reject(signal.reason); }, { once: true });
+        }),
         readGoalCredits: (_ownerId, goal) => estimateGoalCredits(store, goal),
         executeRun: async (context) => {
             if (clearingScene)
@@ -310,6 +315,19 @@ export async function createStandaloneSparkAgentApp(options) {
             clearingScene = false;
         }
     });
+    app.post(`${apiBasePath}/goal-proposals/:toolCallId`, express.json(), (request, response) => {
+        const answer = sparkGoalDecisionSchema.safeParse(request.body);
+        const resolve = goalAnswers.get(request.params.toolCallId);
+        if (!answer.success || answer.data.kind === "unanswered")
+            response.status(400).json({ error: "Answer with a goal or a single try." });
+        else if (!resolve)
+            response.status(404).json({ error: "This goal proposal is no longer waiting for an answer." });
+        else {
+            goalAnswers.delete(request.params.toolCallId);
+            resolve(answer.data);
+            response.status(204).end();
+        }
+    });
     app.use(apiBasePath, (request, response, next) => {
         if (clearingScene && request.method === "POST" && request.path.endsWith("/messages")) {
             response.status(409).json({ error: "The scene is being cleared. Try again when it finishes." });

package/dist/server/types.d.ts

@@ -3,6 +3,7 @@ import type { SparkAgentRun } from "../agent.js";
 import type { ReasoningEffort } from "../models.js";
 import type { SparkRunStatus, SparkUIMessage, StoredSparkChunk } from "../ui.js";
 import type { SparkGoal } from "../goals.js";
+import type { SparkGoalOffer } from "../agent-tools.js";
 export type SparkConversation = {
     id: string;
     ownerId: string;
@@ -38,6 +39,8 @@ export type SparkRun = {
 };
 export type SparkRunExecutionContext = {
     goal?: SparkGoal;
+    /** Set when the host can ask the user to confirm a goal; the executor hands it to the agent. */
+    proposeGoal?: SparkGoalOffer;
     ownerId: string;
     conversationId: string;
     runId: string;

package/dist/ui.d.ts

@@ -3,8 +3,8 @@ export { sparkErrorDiagnostics, sparkErrorDiagnosticsSchema, type SparkErrorDiag
 import type { InferUIMessageChunk, UIMessage } from "ai";
 import type { SceneScreenshotOptions } from "./capabilities/scene.js";
 import { z } from "zod";
-export type { SparkGoal, SparkGoalCommand, SparkGoalCondition, SparkGoalProposal, SparkGoalTry } from "./goals.js";
-import { type SparkGoalProposal } from "./goals.js";
+export type { SparkGoal, SparkGoalCommand, SparkGoalCondition, SparkGoalDecision, SparkGoalOutcome, SparkGoalProposal, SparkGoalProposalPart, SparkGoalTry } from "./goals.js";
+import { type SparkGoalOutcome, type SparkGoalProposal, type SparkGoalProposalPart } from "./goals.js";
 import type { ExecutionReceipt, SparkSkill } from "./capabilities.js";
 export { DEFAULT_MODEL_ID, getSparkModel, REASONING_EFFORT_LABELS, resolveReasoningEffort, SPARK_MODELS, } from "./models.js";
 export type { ModelProvider, ReasoningEffort, SparkModel } from "./models.js";
@@ -92,7 +92,7 @@ export type SparkDataParts = {
     };
     selection: SparkSelectionData;
     compaction: SparkCompaction;
-    goal: SparkGoalProposal;
+    "goal-proposal": SparkGoalProposalPart;
 };
 /** Editor node IDs selected when a user message was sent; never rendered as chat text. */
 export type SparkSelectionData = {
@@ -106,6 +106,12 @@ export type SparkSelectionData = {
 export type SparkCompaction = {
     /** The user message the model reads verbatim from; everything before it is summarized. */
     firstKeptMessageId: string;
+    /**
+     * Set when the summary was written during its turn: the first step of the
+     * recording message the model still reads, counted from 0. Its earlier steps
+     * are summarized too.
+     */
+    firstKeptStep?: number;
     summary: string;
     /** Skills read in the summarized messages; their current text is sent after the summary. */
     skills: string[];
@@ -150,6 +156,13 @@ export type SparkUITools = {
             skills: SkillReadResult[];
         };
     };
+    /** Offered only by hosts that can ask the user; see `SparkGoalOffer`. */
+    propose_goal: {
+        input: SparkGoalProposal;
+        output: {
+            goal: SparkGoalOutcome;
+        };
+    };
 };
 export type SkillReadResult = ({
     ok: true;
@@ -356,6 +369,7 @@ export declare const sparkDataPartSchemas: {
     }, z.core.$strip>;
     readonly compaction: z.ZodObject<{
         firstKeptMessageId: z.ZodString;
+        firstKeptStep: z.ZodOptional<z.ZodNumber>;
         summary: z.ZodString;
         skills: z.ZodArray<z.ZodString>;
         modelId: z.ZodString;
@@ -364,16 +378,24 @@ export declare const sparkDataPartSchemas: {
         createdAt: z.ZodString;
     }, z.core.$strip>;
     /**
-     * The conditions the user confirmed for the goal this message starts. The model
-     * reads it as text (model-history.ts).
+     * The goal the agent proposed in this message, for hosts to show: as the
+     * confirmation while it waits, and as the goal once it started. The model
+     * reads the proposal from its `propose_goal` call, not from this part.
      */
-    readonly goal: z.ZodObject<{
+    readonly "goal-proposal": z.ZodObject<{
         title: z.ZodString;
         conditions: z.ZodArray<z.ZodObject<{
             text: z.ZodString;
             measurable: z.ZodBoolean;
         }, z.core.$strip>>;
+        toolCallId: z.ZodString;
+        outcome: z.ZodOptional<z.ZodEnum<{
+            active: "active";
+            unanswered: "unanswered";
+            started: "started";
+            declined: "declined";
+        }>>;
     }, z.core.$strip>;
 };
 export { parseWompifyCommand, WOMPIFY_PRESETS, wompifyPrompt, wompifyContextSchema, type WompifyRequest, type WompifyContext } from "./wompify.js";
-export { DEFAULT_GOAL_CREDITS, GOAL_CONFIRMATION_DEFAULTS, MAX_GOAL_LENGTH, sparkGoalProposalSchema } from "./goals.js";
+export { DEFAULT_GOAL_CREDITS, GOAL_CONFIRMATION_DEFAULTS, sparkGoalProposalPartSchema, sparkGoalProposalSchema } from "./goals.js";