@womp/spark-agent 6.2.0 → 6.4.0

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 } from "../goals.js";
+import { sparkGoalCommandSchema, sparkGoalProposalSchema } from "../goals.js";
 import { goalVerdictSchema } from "./goal-evaluator.js";
 import { wompifyContextSchema, WompifyCreditCapReachedError } from "../wompify.js";
 const TERMINAL_STATUSES = new Set([
@@ -52,13 +52,14 @@ function titleFor(message) {
         return "New build";
     return text.length > 44 ? `${text.slice(0, 44)}…` : text;
 }
-function normalizeUserMessage(message) {
+/** `confirmedGoal` admits the goal part, which only a `set` command attaches. */
+function normalizeUserMessage(message, confirmedGoal = false) {
     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")
+        if (part.type === "text" || part.type === "data-selection" || (confirmedGoal && part.type === "data-goal"))
             continue;
         if (part.type === "file" &&
             part.mediaType.startsWith("image/") &&
@@ -84,10 +85,21 @@ const GOAL_WORK_RULES = "Keep working toward this objective and verify it with c
  * turn reuses the provider's cached prefix.
  */
 function goalContinuationText(goal) {
+    const open = goal.conditions?.filter((condition) => condition.measurable && condition.met !== true) ?? [];
     return `Continue working toward the goal: ${goal.objective}\n${GOAL_WORK_RULES}\nProgress check: ${goal.lastReason}`
+        + (open.length ? `\nConditions not yet verified:${open.map(({ text, reason }) => `\n- ${text}${reason ? ` (${reason})` : ""}`).join("")}` : "")
         + (wompifyContextSchema.safeParse(goal.settings.wompify).success
             ? "\nKeep refining the existing reconstruction at the same detail level. Compare it with the reference and improve the remaining shape and color discrepancies." : "");
 }
+/** The goal's conditions with what this evaluation found for each measurable one. */
+function judgedConditions(goal, evaluation) {
+    if (!goal.conditions || !evaluation?.conditions)
+        return goal.conditions;
+    return goal.conditions.map((condition, index) => {
+        const result = evaluation.conditions.find((entry) => entry.index === index + 1);
+        return result && condition.measurable ? { ...condition, met: result.met, reason: result.reason } : condition;
+    });
+}
 function goalStartText(goal, action) {
     return `${action === "set" ? "Goal" : "Resume the goal"}: ${goal.objective}\n${GOAL_WORK_RULES}`;
 }
@@ -95,6 +107,7 @@ export class SparkAgentService {
     store;
     executeRun;
     evaluateGoal;
+    proposer;
     readGoalCredits;
     continuationSettings;
     closing = false;
@@ -113,6 +126,7 @@ export class SparkAgentService {
         this.store = options.store;
         this.executeRun = options.executeRun;
         this.evaluateGoal = options.evaluateGoal;
+        this.proposer = options.proposeGoal;
         this.readGoalCredits = options.readGoalCredits;
         this.continuationSettings = options.continuationSettings;
         this.endOrphanedRuns = options.endOrphanedRuns ?? false;
@@ -153,6 +167,21 @@ 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);
@@ -171,10 +200,18 @@ export class SparkAgentService {
                     throw new SparkServiceError(409, "This goal is already complete.");
                 if (wompifyContextSchema.safeParse(current.settings.wompify).success)
                     throw new SparkServiceError(409, "Wompify caps are set by the detail level.");
-                const goal = await this.refreshGoalCredits(ownerId, { ...current, creditBudget: command.creditBudget });
-                if (command.creditBudget < goal.creditsUsed)
+                if (command.creditBudget === undefined && command.maxTurns === undefined)
+                    throw new SparkServiceError(400, "Give a credit cap or a tries cap to change.");
+                const goal = await this.refreshGoalCredits(ownerId, {
+                    ...current,
+                    ...(command.creditBudget === undefined ? {} : { creditBudget: command.creditBudget }),
+                    ...(command.maxTurns === undefined ? {} : { maxTurns: command.maxTurns }),
+                });
+                if (command.creditBudget !== undefined && command.creditBudget < goal.creditsUsed)
                     throw new SparkServiceError(409, "The cap cannot be lower than credits already used and pending. Refresh and try again.");
-                if (goal.creditsUsed >= goal.creditBudget) {
+                if (command.maxTurns !== undefined && command.maxTurns < goal.turns)
+                    throw new SparkServiceError(409, "The tries cap cannot be lower than the tries already used. Refresh and try again.");
+                if (goal.creditBudget !== undefined && goal.creditsUsed >= goal.creditBudget) {
                     goal.status = "budget_limited";
                     goal.lastReason = "The goal reached its credit budget.";
                 }
@@ -224,19 +261,24 @@ 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, };
-            const inputMessage = normalizeUserMessage(message ?? {
+            // 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") } : {
                 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");
+                const run = await this.submitInTurn({ ownerId, conversationId, trigger: "submit-message", message: inputMessage, settings: goal.settings }, command.action === "resume", true);
                 return { goal: (await this.getConversation(ownerId, conversationId)).goal, run };
             }
             catch (error) {
@@ -300,7 +342,7 @@ export class SparkAgentService {
     async submitMessage(input) {
         return this.inConversationTurn(input.conversationId, () => this.submitInTurn(input));
     }
-    async submitInTurn(input, goalContinuation = false) {
+    async submitInTurn(input, goalContinuation = false, confirmedGoal = false) {
         if (this.closing)
             throw new SparkServiceError(503, "The service is shutting down.");
         const conversation = await this.getConversation(input.ownerId, input.conversationId);
@@ -328,7 +370,7 @@ export class SparkAgentService {
             inputMessage = previous;
         }
         else {
-            inputMessage = normalizeUserMessage(input.message);
+            inputMessage = normalizeUserMessage(input.message, confirmedGoal);
             if (goalContinuation)
                 inputMessage.metadata = { ...inputMessage.metadata, goalContinuation: true };
             if (conversation.messages.some(({ id }) => id === inputMessage.id)) {
@@ -636,16 +678,26 @@ export class SparkAgentService {
                 await this.store.saveConversationGoal(conversation.id, current);
                 return;
             }
+            const conditions = judgedConditions(current, evaluation);
             const next = {
                 ...current,
+                ...(conditions ? { conditions } : {}),
+                ...(conditions && evaluation ? {
+                    tries: [...(current.tries ?? []), {
+                            turn: current.turns, runId: run.id, reason: evaluation.reason,
+                            conditions: conditions.map(({ met, reason }) => ({ ...(met === undefined ? {} : { met }), ...(reason === undefined ? {} : { reason }) })),
+                        }],
+                } : {}),
                 idleTurns: usedTools ? 0 : (current.idleTurns ?? 0) + 1,
                 updatedAt: now(), lastReason: evaluation?.reason,
             };
+            // A verdict of met cannot stand over a condition the same evaluation found unmet.
+            const met = evaluation?.verdict === "met" && !conditions?.some((condition) => condition.measurable && condition.met === false);
             if (signal.aborted || this.closing) {
                 next.status = "paused";
                 next.lastReason = "The goal was interrupted. Resume to continue.";
             }
-            else if (evaluation?.verdict === "met" && !wompify)
+            else if (met && !wompify)
                 next.status = "completed";
             else if (evaluation?.verdict === "blocked")
                 next.status = "blocked";

package/dist/server/standalone.d.ts

@@ -1,5 +1,7 @@
 import { type Express } from "express";
 import { KakapoAPI } from "@womp/kakapo-sdk";
+import type { SparkGoal } from "../goals.js";
+import type { SparkAgentStore } from "./types.js";
 export type StandaloneSparkAgentOptions = {
     openAiApiKey?: string;
     anthropicApiKey?: string;
@@ -17,6 +19,12 @@ export type StandaloneSparkAgentOptions = {
 export type StandaloneSparkAgentApp = Express & {
     dispose(): Promise<void>;
 };
+/**
+ * A development fixture, not billing: the standalone server charges nothing, so
+ * a goal's credit cap is checked against the model cost its finished tries
+ * reported. Evaluations and the try in progress are not counted.
+ */
+export declare function estimateGoalCredits(store: Pick<SparkAgentStore, "getRun" | "getConversation">, goal: SparkGoal): Promise<number>;
 export declare function checkStandaloneServices(api: Pick<KakapoAPI, "listFonts" | "validateOpenScad">): Promise<{
     fonts: import("@womp/kakapo-sdk").FontFamily[];
     fontsAvailable: boolean;

package/dist/server/standalone.js

@@ -18,11 +18,34 @@ import { hasSceneResourcePressure, } from "../scene-health.js";
 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 { createSparkAgentRouter } from "./express.js";
 import { SparkAgentService } from "./service.js";
 import { SqliteSparkStore } from "./sqlite-store.js";
 import { clearSceneContents } from "./scene-actions.js";
 import { standaloneSceneAccess } from "./scene-access.js";
+/** Production's list rate: 1,000 credits per USD of model cost, with its 1.25 markup. */
+const DEVELOPMENT_CREDITS_PER_USD = 1_250;
+/**
+ * A development fixture, not billing: the standalone server charges nothing, so
+ * a goal's credit cap is checked against the model cost its finished tries
+ * reported. Evaluations and the try in progress are not counted.
+ */
+export async function estimateGoalCredits(store, goal) {
+    const run = goal.runId === undefined ? undefined : await store.getRun(goal.runId);
+    const conversation = run && await store.getConversation(run.conversationId);
+    let usd = 0;
+    for (const message of conversation?.messages ?? []) {
+        const runId = message.role === "assistant" ? message.metadata?.runId : undefined;
+        if (runId === undefined || (await store.getRun(runId))?.goalId !== goal.id)
+            continue;
+        for (const part of message.parts)
+            if (part.type === "data-step-metrics")
+                usd += part.data.cost?.totalUsd ?? 0;
+    }
+    return Math.ceil(usd * DEVELOPMENT_CREDITS_PER_USD);
+}
 export async function checkStandaloneServices(api) {
     const [fonts, openScad] = await Promise.allSettled([
         api.listFonts(),
@@ -172,49 +195,56 @@ export async function createStandaloneSparkAgentApp(options) {
                 throw error;
             }
         },
-        resolveModel: (settings) => {
-            const selected = getSparkModel(settings.modelId);
-            if (SPARK_MODELS.some(({ id }) => id === settings.modelId) === false) {
-                throw new Error(`Unsupported Spark model: ${settings.modelId}`);
-            }
-            if (selected.provider === "anthropic") {
-                if (options.anthropicApiKey?.trim() === "" ||
-                    options.anthropicApiKey === undefined) {
-                    throw new Error("ANTHROPIC_API_KEY is required for this model.");
-                }
-                return {
-                    model: createAnthropic({ apiKey: options.anthropicApiKey })(selected.id),
-                    modelId: selected.id,
-                    providerOptions: sparkModelOptions(selected.id, selected.provider, settings.reasoningEffort),
-                    maxOutputTokens: 48_000,
-                };
-            }
-            if (selected.provider === "google") {
-                if (!options.geminiApiKey?.trim()) {
-                    throw new Error("GEMINI_API_KEY is required for this model.");
-                }
-                return {
-                    model: createGoogleGenerativeAI({ apiKey: options.geminiApiKey })(selected.id),
-                    modelId: selected.id,
-                    providerOptions: sparkModelOptions(selected.id, selected.provider, settings.reasoningEffort),
-                    maxOutputTokens: 48_000,
-                };
+        resolveModel,
+    });
+    function resolveModel(settings) {
+        const selected = getSparkModel(settings.modelId);
+        if (SPARK_MODELS.some(({ id }) => id === settings.modelId) === false) {
+            throw new Error(`Unsupported Spark model: ${settings.modelId}`);
+        }
+        if (selected.provider === "anthropic") {
+            if (options.anthropicApiKey?.trim() === "" ||
+                options.anthropicApiKey === undefined) {
+                throw new Error("ANTHROPIC_API_KEY is required for this model.");
             }
-            if (options.openAiApiKey?.trim() === "" ||
-                options.openAiApiKey === undefined) {
-                throw new Error("OPENAI_API_KEY is required for this model.");
+            return {
+                model: createAnthropic({ apiKey: options.anthropicApiKey })(selected.id),
+                modelId: selected.id,
+                providerOptions: sparkModelOptions(selected.id, selected.provider, settings.reasoningEffort),
+                maxOutputTokens: 48_000,
+            };
+        }
+        if (selected.provider === "google") {
+            if (!options.geminiApiKey?.trim()) {
+                throw new Error("GEMINI_API_KEY is required for this model.");
             }
             return {
-                model: createOpenAI({ apiKey: options.openAiApiKey }).responses(selected.id),
+                model: createGoogleGenerativeAI({ apiKey: options.geminiApiKey })(selected.id),
                 modelId: selected.id,
                 providerOptions: sparkModelOptions(selected.id, selected.provider, settings.reasoningEffort),
                 maxOutputTokens: 48_000,
             };
-        },
-    });
+        }
+        if (options.openAiApiKey?.trim() === "" ||
+            options.openAiApiKey === undefined) {
+            throw new Error("OPENAI_API_KEY is required for this model.");
+        }
+        return {
+            model: createOpenAI({ apiKey: options.openAiApiKey }).responses(selected.id),
+            modelId: selected.id,
+            providerOptions: sparkModelOptions(selected.id, selected.provider, settings.reasoningEffort),
+            maxOutputTokens: 48_000,
+        };
+    }
     let clearingScene = false;
     let activeRuns = 0;
-    const service = new SparkAgentService({ store, executeRun: async (context) => {
+    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" }) }),
+        readGoalCredits: (_ownerId, goal) => estimateGoalCredits(store, goal),
+        executeRun: async (context) => {
             if (clearingScene)
                 throw new Error("The scene is being cleared. Try again when it finishes.");
             activeRuns++;
@@ -226,7 +256,8 @@ export async function createStandaloneSparkAgentApp(options) {
                 activeRuns--;
                 throw error;
             }
-        } });
+        },
+    });
     try {
         for (const run of await store.listInterruptedRuns())
             await service.recoverInterruptedRun(run.id);

package/dist/ui.d.ts

@@ -3,7 +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 } from "./goals.js";
+export type { SparkGoal, SparkGoalCommand, SparkGoalCondition, SparkGoalProposal, SparkGoalTry } from "./goals.js";
+import { type SparkGoalProposal } 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";
@@ -90,11 +91,31 @@ export type SparkDataParts = {
         receipt: ExecutionReceipt;
     };
     selection: SparkSelectionData;
+    compaction: SparkCompaction;
+    goal: SparkGoalProposal;
 };
 /** Editor node IDs selected when a user message was sent; never rendered as chat text. */
 export type SparkSelectionData = {
     nodeIds: string[];
 };
+/**
+ * A summary of a long conversation's earlier messages, recorded on the assistant
+ * message of the turn that wrote it. The model is sent the summary in place of
+ * every message before `firstKeptMessageId`; the chat still shows all of them.
+ */
+export type SparkCompaction = {
+    /** The user message the model reads verbatim from; everything before it is summarized. */
+    firstKeptMessageId: string;
+    summary: string;
+    /** Skills read in the summarized messages; their current text is sent after the summary. */
+    skills: string[];
+    /** The model that wrote the summary. */
+    modelId: string;
+    /** The conversation's size before and after, in tokens. */
+    tokensBefore: number;
+    tokensAfter: number;
+    createdAt: string;
+};
 export type ExecuteJavaScriptInput = {
     purpose: string;
     code: string;
@@ -333,6 +354,26 @@ export declare const sparkDataPartSchemas: {
     readonly selection: z.ZodObject<{
         nodeIds: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
+    readonly compaction: z.ZodObject<{
+        firstKeptMessageId: z.ZodString;
+        summary: z.ZodString;
+        skills: z.ZodArray<z.ZodString>;
+        modelId: z.ZodString;
+        tokensBefore: z.ZodNumber;
+        tokensAfter: z.ZodNumber;
+        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).
+     */
+    readonly goal: z.ZodObject<{
+        title: z.ZodString;
+        conditions: z.ZodArray<z.ZodObject<{
+            text: z.ZodString;
+            measurable: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
 };
 export { parseWompifyCommand, WOMPIFY_PRESETS, wompifyPrompt, wompifyContextSchema, type WompifyRequest, type WompifyContext } from "./wompify.js";
-export { parseSparkGoalCommand, DEFAULT_GOAL_CREDITS } from "./goals.js";
+export { DEFAULT_GOAL_CREDITS, GOAL_CONFIRMATION_DEFAULTS, MAX_GOAL_LENGTH, sparkGoalProposalSchema } from "./goals.js";

package/dist/ui.js

@@ -1,6 +1,7 @@
 import { sparkErrorDiagnosticsSchema } from "./error-diagnostics.js";
 export { sparkErrorDiagnostics, sparkErrorDiagnosticsSchema, } from "./error-diagnostics.js";
 import { z } from "zod";
+import { sparkGoalProposalSchema } from "./goals.js";
 export { DEFAULT_MODEL_ID, getSparkModel, REASONING_EFFORT_LABELS, resolveReasoningEffort, SPARK_MODELS, } from "./models.js";
 export const SPARK_RUN_STATUSES = [
     "queued",
@@ -85,6 +86,20 @@ export const sparkDataPartSchemas = {
      */
     // Editor ids are the engine's decimal integers; 8192 covers a select-all at the engine's budgets.
     selection: z.object({ nodeIds: z.array(z.string().min(1).max(64)).min(1).max(8192) }),
+    compaction: z.object({
+        firstKeptMessageId: z.string().min(1),
+        summary: z.string().min(1),
+        skills: z.array(z.string().min(1)),
+        modelId: z.string(),
+        tokensBefore: z.number().int().nonnegative(),
+        tokensAfter: z.number().int().nonnegative(),
+        createdAt: z.string().datetime(),
+    }),
+    /**
+     * The conditions the user confirmed for the goal this message starts. The model
+     * reads it as text (model-history.ts).
+     */
+    goal: sparkGoalProposalSchema,
 };
 export { parseWompifyCommand, WOMPIFY_PRESETS, wompifyPrompt, wompifyContextSchema } from "./wompify.js";
-export { parseSparkGoalCommand, DEFAULT_GOAL_CREDITS } from "./goals.js";
+export { DEFAULT_GOAL_CREDITS, GOAL_CONFIRMATION_DEFAULTS, MAX_GOAL_LENGTH, sparkGoalProposalSchema } from "./goals.js";

package/dist/user-images.d.ts

@@ -0,0 +1,10 @@
+import type { SparkUIMessage } from "./ui.js";
+export type SparkFilePart = Extract<SparkUIMessage["parts"][number], {
+    type: "file";
+}>;
+/**
+ * The images the user attached to `messages`, each once, in the order sent:
+ * what the work is often built from, so the model calls that do or judge it
+ * keep them longest.
+ */
+export declare function userImages(messages: readonly SparkUIMessage[]): SparkFilePart[];

package/dist/user-images.js

@@ -0,0 +1,20 @@
+/**
+ * The images the user attached to `messages`, each once, in the order sent:
+ * what the work is often built from, so the model calls that do or judge it
+ * keep them longest.
+ */
+export function userImages(messages) {
+    const seen = new Set();
+    const images = [];
+    for (const message of messages) {
+        if (message.role !== "user")
+            continue;
+        for (const part of message.parts) {
+            if (part.type !== "file" || !part.mediaType.startsWith("image/") || seen.has(part.url))
+                continue;
+            seen.add(part.url);
+            images.push(part);
+        }
+    }
+    return images;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/spark-agent",
-  "version": "6.2.0",
+  "version": "6.4.0",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",