@love-moon/ai-sdk 0.3.1 → 0.4.0

package/dist/providers/claude-agent-sdk-session.js

@@ -1,6 +1,6 @@
 import { EventEmitter } from "node:events";
 import { CLAUDE_AGENT_SDK_VARIANT as CLAUDE_PROVIDER_VARIANT } from "../built-in-backends.js";
-import { emitLog, getBoundedEnvInt, loadEnvConfig, normalizeLogger, proxyToEnv, sanitizeForLog, } from "../shared.js";
+import { emitLog, getBoundedEnvInt, isGoalStatus, loadEnvConfig, normalizeLogger, proxyToEnv, sanitizeForLog, } from "../shared.js";
 const DEFAULT_TURN_DEADLINE_MS = 12 * 60 * 1000;
 const MIN_TURN_DEADLINE_MS = 30 * 1000;
 const MAX_TURN_DEADLINE_MS = 30 * 60 * 1000;
@@ -126,6 +126,13 @@ function sanitizeSummary(value, maxLen = 180) {
     return sanitizeForLog(value, maxLen);
 }
 export class ClaudeAgentSdkSession extends EventEmitter {
+    // Capability advertised via getSnapshot().capabilities so worker proxies
+    // can short-circuit runGoal without an IPC round trip. Claude exposes
+    // native `/goal` slash command, so this is true.
+    static capabilities = Object.freeze({ goal: true });
+    getCapabilities() {
+        return { ...ClaudeAgentSdkSession.capabilities };
+    }
     constructor(backend, options = {}) {
         super();
         this.backend = normalizeClaudeBackend(backend);
@@ -207,6 +214,7 @@ export class ClaudeAgentSdkSession extends EventEmitter {
                 }
                 : null,
             currentTurnStatus: this.getCurrentTurnStatus(),
+            capabilities: this.getCapabilities(),
         };
     }
     getSessionInfo() {
@@ -869,6 +877,106 @@ export class ClaudeAgentSdkSession extends EventEmitter {
             }
         }
     }
+    /**
+     * Trigger Claude's native `/goal` slash command. Implemented by sending the
+     * prompt `"/goal <objective>"` through {@link runTurn}, which the Claude
+     * Agent SDK natively recognizes as a long-running goal request.
+     *
+     * Callers should detect support via `typeof session.runGoal === "function"`.
+     * When a provider does not support goals it should leave this method
+     * undefined; callers MUST surface a clear error rather than silently falling
+     * back to {@link runTurn}.
+     *
+     * Implementation note (N8): Claude's `/goal` slash command resolves the
+     * entire goal within a single `query()` iteration. {@link runTurn} drains
+     * the SDK iterator to completion (`for await (const message of query)`)
+     * before returning, so `turnResult.items` is the full, terminal sequence of
+     * messages. If the SDK emits multiple `goal_status` items (e.g. an
+     * intermediate "active" followed by a terminal "complete"), we select the
+     * LAST one rather than the first so the goal's final state is reflected.
+     * When no `goal_status` item is present we fall back to "active" and emit a
+     * debug log; that fallback is a signal that the contract has drifted.
+     *
+     * @param {import("../shared.js").GoalRequest} goal
+     * @param {object} [options]
+     * @returns {Promise<import("../shared.js").GoalResult>}
+     */
+    async runGoal(goal, options = {}) {
+        const objective = typeof goal?.objective === "string" ? goal.objective.trim() : "";
+        if (!objective) {
+            throw createTurnError("runGoal requires a non-empty objective", {
+                reason: "invalid_goal",
+            });
+        }
+        const prompt = `/goal ${objective}`;
+        const turnResult = await this.runTurn(prompt, options);
+        const items = Array.isArray(turnResult?.items) ? turnResult.items : [];
+        // Walk from the end so we settle on the LAST goal_status item the SDK
+        // emitted. The single-shot `query()` iteration has been drained by
+        // `runTurn`, so this is the terminal status.
+        let goalStatusItem = null;
+        for (let idx = items.length - 1; idx >= 0; idx -= 1) {
+            const item = items[idx];
+            if (!item || typeof item !== "object") {
+                continue;
+            }
+            if (item.type === "goal_status" ||
+                item.subtype === "goal_status" ||
+                (item.goal_status && typeof item.goal_status === "object")) {
+                goalStatusItem = item;
+                break;
+            }
+        }
+        const parsedStatus = (() => {
+            if (!goalStatusItem) {
+                return null;
+            }
+            const candidate = goalStatusItem.goal_status && typeof goalStatusItem.goal_status === "object"
+                ? goalStatusItem.goal_status
+                : goalStatusItem;
+            const status = typeof candidate?.status === "string" ? candidate.status : null;
+            const id = typeof candidate?.id === "string" ? candidate.id : undefined;
+            const tokenBudget = candidate?.tokenBudget === null || Number.isFinite(Number(candidate?.tokenBudget))
+                ? candidate.tokenBudget
+                : undefined;
+            return { status, id, tokenBudget };
+        })();
+        if (!goalStatusItem) {
+            // Contract drift: the SDK did not surface a goal_status item in the
+            // single query iteration. Log so operators notice; downstream we
+            // default to "active" so a still-running goal isn't misclassified as
+            // terminal.
+            this.trace(`runGoal: no goal_status item found in SDK message stream (${items.length} items); defaulting status to "active"`);
+        }
+        // Validate the SDK-reported status against the known GoalStatus enum
+        // before exposing it. An unknown / typo'd status (e.g. "weird") would
+        // otherwise leak through and confuse downstream goal-status consumers
+        // (the realtime hub uses isTerminalGoalStatus to decide when to stop
+        // polling). Default to "active" so a still-running goal is not
+        // misclassified as terminal.
+        const rawStatus = typeof parsedStatus?.status === "string" ? parsedStatus.status.trim() : "";
+        const validatedStatus = isGoalStatus(rawStatus) ? rawStatus : "active";
+        const goalState = {
+            id: parsedStatus?.id,
+            threadId: this.sessionId || undefined,
+            objective,
+            status: validatedStatus,
+            tokenBudget: goal?.tokenBudget !== undefined
+                ? goal.tokenBudget
+                : parsedStatus?.tokenBudget !== undefined
+                    ? parsedStatus.tokenBudget
+                    : null,
+        };
+        return {
+            text: turnResult?.text || "",
+            goal: goalState,
+            usage: turnResult?.usage || null,
+            metadata: {
+                ...(turnResult?.metadata && typeof turnResult.metadata === "object" ? turnResult.metadata : {}),
+                goalPrompt: prompt,
+            },
+        };
+    }
     async close() {
         if (this.closed) {
             return;

package/dist/providers/codex-app-server-session.d.ts

@@ -1,5 +1,15 @@
 export class CodexAppServerSession extends EventEmitter<[never]> {
+    /**
+     * Optional feature flags surfaced to callers via {@link getSnapshot}.
+     * Treat as read-only.
+     * @type {Readonly<import("../shared.js").SessionCapabilities>}
+     */
+    static capabilities: Readonly<import("../shared.js").SessionCapabilities>;
     constructor(backend: any, options?: {});
+    /**
+     * @returns {import("../shared.js").SessionCapabilities}
+     */
+    getCapabilities(): import("../shared.js").SessionCapabilities;
     backend: string;
     options: {};
     logger: any;
@@ -32,9 +42,36 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
         activeAssistantMessageText: string;
         resolve: null;
         reject: null;
+    } | {
+        turnId: string;
+        fullText: string;
+        activeAssistantMessageId: string;
+        activeAssistantMessageText: string;
+        resolve: () => void;
+        reject: (error: any) => void;
+        goalMode: boolean;
     } | null;
     bootPromise: Promise<void> | null;
     booted: boolean;
+    goalMode: boolean;
+    currentGoal: (import("../shared.js").GoalState & {
+        raw?: unknown;
+    }) | null;
+    currentGoalRun: {
+        id: undefined;
+        threadId: any;
+        objective: string;
+        status: string;
+        tokenBudget: number | null;
+        fullText: string;
+        lastTurnText: string;
+        latestGoal: null;
+        completion: Promise<any>;
+        pendingDeltasByTurnId: Map<any, any>;
+        handleGoalUpdate: (payload: any) => void;
+        handleGoalCleared: (previous: any) => void;
+        handleTurnFailed: (error: any) => void;
+    } | null;
     transport: CodexAppServerTransport;
     writeLog(message: any): void;
     trace(message: any): void;
@@ -56,6 +93,7 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
             command: string;
         } | null;
         currentTurnStatus: any;
+        capabilities: import("../shared.js").SessionCapabilities;
         pid: number | undefined;
     };
     getSessionInfo(): any;
@@ -109,6 +147,14 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
         activeAssistantMessageText: string;
         resolve: null;
         reject: null;
+    } | {
+        turnId: string;
+        fullText: string;
+        activeAssistantMessageId: string;
+        activeAssistantMessageText: string;
+        resolve: () => void;
+        reject: (error: any) => void;
+        goalMode: boolean;
     } | null, { messageId }?: {
         messageId?: string | undefined;
     }): Promise<boolean>;
@@ -133,6 +179,14 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
         activeAssistantMessageText: string;
         resolve: null;
         reject: null;
+    } | {
+        turnId: string;
+        fullText: string;
+        activeAssistantMessageId: string;
+        activeAssistantMessageText: string;
+        resolve: () => void;
+        reject: (error: any) => void;
+        goalMode: boolean;
     } | null;
     ensureCurrentTurn(params: any): {
         turnId: string;
@@ -141,6 +195,14 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
         activeAssistantMessageText: string;
         resolve: null;
         reject: null;
+    } | {
+        turnId: string;
+        fullText: string;
+        activeAssistantMessageId: string;
+        activeAssistantMessageText: string;
+        resolve: () => void;
+        reject: (error: any) => void;
+        goalMode: boolean;
     } | null;
     queueAssistantDelta(delta: any, { messageId }?: {
         messageId?: string | undefined;
@@ -173,6 +235,51 @@ export class CodexAppServerSession extends EventEmitter<[never]> {
             nativeSessionId: string | undefined;
         };
     }>;
+    /**
+     * Normalize a goal payload from a codex `thread/goal/*` notification into
+     * the cross-layer {@link GoalState} shape.
+     *
+     * @param {unknown} payload
+     * @returns {(import("../shared.js").GoalState & { raw?: unknown }) | null}
+     */
+    normalizeGoalPayload(payload: unknown): (import("../shared.js").GoalState & {
+        raw?: unknown;
+    }) | null;
+    /**
+     * Trigger Codex's experimental `thread/goal/set` JSON-RPC. Requires the
+     * app-server to have been booted with `--enable goals`; dynamic enablement
+     * is NOT supported. Pass `{ goalMode: true }` to the session factory so the
+     * transport spawns with the right flag.
+     *
+     * Resolves when the goal reaches a terminal status (`complete`, `blocked`,
+     * `usageLimited`, `budgetLimited`) or when a `thread/goal/cleared`
+     * notification arrives.
+     *
+     * @param {import("../shared.js").GoalRequest} goal
+     * @param {object} [options]
+     * @returns {Promise<import("../shared.js").GoalResult>}
+     */
+    runGoal(goal: import("../shared.js").GoalRequest, options?: object): Promise<import("../shared.js").GoalResult>;
+    /**
+     * Fetch the current goal via `thread/goal/get`.
+     *
+     * @returns {Promise<import("../shared.js").GoalState | null>}
+     */
+    getGoal(): Promise<import("../shared.js").GoalState | null>;
+    /**
+     * Clear the current goal via `thread/goal/clear`.
+     *
+     * If a {@link runGoal} call is in flight when this is invoked externally,
+     * the pending `currentGoalRun.completion` is unblocked with a synthetic
+     * "cleared" payload so the caller's `await runGoal(...)` resolves promptly
+     * instead of waiting for the turn-timeout. The server-initiated
+     * `thread/goal/clear` does not emit a `thread/goal/cleared` notification
+     * (it's the response to OUR own RPC), so we have to wake the goal-run
+     * ourselves here.
+     *
+     * @returns {Promise<boolean>} true if a goal was cleared, false if there was nothing to clear.
+     */
+    clearGoal(): Promise<boolean>;
     close(): Promise<void>;
 }
 import { EventEmitter } from "node:events";