sakura-agent 0.1.0 → 0.1.1

package/dist/packages/session/src/log-core.js

@@ -0,0 +1,47 @@
+import { randomUUID } from "node:crypto";
+import { projectMessages } from "./projection.js";
+/**
+ * The one implementation of "a log": entries in a tree, one leaf, appends in order. The log is only as durable as its storage, and a log and its
+ * storage never disagree: an entry joins the tree after it is saved, and an append that fails changes nothing and does not stop the ones after it.
+ */
+export function createLog(tree, storage, options = {}) {
+    const now = options.now ?? Date.now;
+    const newId = options.newId ?? (() => randomUUID().slice(0, 8));
+    // Appends run one after another, each starting from where the one before ended. A failed one is reported to its caller and not to the next.
+    let queue = Promise.resolve();
+    return {
+        /** Resolves when everything started so far has been saved or has failed. */
+        settled: () => queue.then(() => undefined, () => undefined),
+        append(body) {
+            const run = queue.then(async () => {
+                const entry = { ...body, id: newId(), parentId: tree.leaf(), ts: now() };
+                await storage.saveEntry(entry);
+                tree.add(entry);
+                return entry;
+            });
+            queue = run.catch(() => undefined);
+            return run;
+        },
+        async branch() {
+            return tree.branch();
+        },
+        async project(upTo) {
+            const branch = tree.branch();
+            return projectMessages(upTo === undefined
+                ? branch
+                : branch.slice(0, Math.max(0, branch.findIndex((entry) => entry.id === upTo))));
+        },
+        /**
+         * Takes effect at once. Entries that were already waiting to be saved follow the new end, so do not rewind while appends are in flight
+         * (the kernel does not: one run at a time, and it waits for each append).
+         */
+        rewindTo(entryId) {
+            const before = tree.leaf();
+            tree.moveLeaf(entryId);
+            if (entryId === before)
+                return;
+            queue = queue.then(() => storage.saveRewind(entryId)).catch(() => undefined);
+        },
+        leaf: () => tree.leaf(),
+    };
+}

package/dist/packages/session/src/memory-log.d.ts

@@ -1,15 +1,6 @@
-import type { Log, LogEntry } from "../../kernel/src/index.js";
-export interface LogOptions {
-    now?: () => number;
-    newId?: () => string;
-}
-/** A session log that can go back to an earlier entry and carry on from there. */
-export interface RewindableLog extends Log {
-    /** Moves the end of the conversation back to an earlier entry (or to the very start with null). Later entries start a new branch. */
-    rewindTo(entryId: string | null): void;
-    /** Id of the entry the next one will follow. */
-    leaf(): string | null;
-}
+import type { LogEntry } from "../../kernel/src/index.js";
+import type { LogOptions, RewindableLog } from "./log-core.js";
+export type { LogOptions, RewindableLog } from "./log-core.js";
 /** A log that lives only in memory (or wraps entries that were loaded elsewhere). */
 export declare function createMemoryLog(options?: LogOptions & {
     entries?: readonly LogEntry[];

package/dist/packages/session/src/memory-log.js

@@ -1,27 +1,7 @@
-import { randomUUID } from "node:crypto";
-import { projectMessages } from "./projection.js";
+import { createLog } from "./log-core.js";
 import { createTree } from "./tree.js";
 /** A log that lives only in memory (or wraps entries that were loaded elsewhere). */
 export function createMemoryLog(options = {}) {
-    const now = options.now ?? Date.now;
-    const newId = options.newId ?? (() => randomUUID().slice(0, 8));
-    const tree = createTree(options.entries ?? []);
-    return {
-        async append(body) {
-            const entry = { ...body, id: newId(), parentId: tree.leaf(), ts: now() };
-            tree.add(entry);
-            return entry;
-        },
-        async branch() {
-            return tree.branch();
-        },
-        async project(upTo) {
-            const branch = tree.branch();
-            return projectMessages(upTo === undefined
-                ? branch
-                : branch.slice(0, Math.max(0, branch.findIndex((entry) => entry.id === upTo))));
-        },
-        rewindTo: (entryId) => tree.moveLeaf(entryId),
-        leaf: () => tree.leaf(),
-    };
+    const { settled: _settled, ...log } = createLog(createTree(options.entries ?? []), { saveEntry: async () => undefined, saveRewind: async () => undefined }, options);
+    return log;
 }

package/dist/packages/session/src/projection.js

@@ -64,6 +64,8 @@ export function projectMessages(branch) {
         const entry = branch[index];
         if (entry?.type !== "custom_message" || !entry.pinned)
             continue;
+        if (edits.get(entry.id) === null)
+            continue; // a pinned message can be withdrawn too (an earlier goal)
         const message = entryToMessage(entry);
         if (message)
             messages.push(message);

package/dist/packages/testing/src/faux.d.ts

@@ -0,0 +1,36 @@
+import type { LlmClient, LlmRequest, ProviderError, StopReason, Usage } from "../../kernel/src/index.js";
+export interface FauxTurn {
+    text?: string;
+    reasoning?: string;
+    toolCalls?: Array<{
+        name: string;
+        args: unknown;
+        id?: string;
+    }>;
+    /** Cut the output off in the middle of this tool call (finish_reason "length"). */
+    truncatedToolCall?: {
+        name: string;
+        id?: string;
+    };
+    usage?: Partial<Usage>;
+    stop?: StopReason;
+    /** Fail the request instead of answering. */
+    error?: ProviderError;
+    /** Never answer; wait until the request is aborted. */
+    hang?: boolean;
+    /** Send this text, then a restart (as an adapter does after a dropped connection), then the real reply. */
+    droppedFirst?: string;
+    /** Split text into pieces of this many characters (default: one piece). */
+    chunkSize?: number;
+}
+export type FauxScript = FauxTurn[] | ((request: LlmRequest, index: number) => FauxTurn);
+export interface FauxClient extends LlmClient {
+    /** Every request received, in order. */
+    requests: LlmRequest[];
+}
+export interface FauxOptions {
+    contextWindow?: number;
+    supportsImages?: boolean;
+}
+/** A scripted stand-in for a model: replays the given turns, one per request. */
+export declare function createFauxClient(script: FauxScript, options?: FauxOptions): FauxClient;

package/dist/packages/testing/src/faux.js

@@ -0,0 +1,69 @@
+function abortError() {
+    const error = new Error("aborted");
+    error.name = "AbortError";
+    return error;
+}
+function waitForAbort(signal) {
+    return new Promise((_, reject) => {
+        if (signal.aborted)
+            reject(abortError());
+        signal.addEventListener("abort", () => reject(abortError()), { once: true });
+    });
+}
+function estimateTokens(value) {
+    return Math.ceil(JSON.stringify(value).length / 4);
+}
+function* pieces(value, size) {
+    if (!size || size >= value.length) {
+        yield value;
+        return;
+    }
+    for (let start = 0; start < value.length; start += size)
+        yield value.slice(start, start + size);
+}
+/** A scripted stand-in for a model: replays the given turns, one per request. */
+export function createFauxClient(script, options = {}) {
+    const requests = [];
+    let callCount = 0;
+    return {
+        requests,
+        model: { id: "faux", contextWindow: options.contextWindow ?? 100_000, supportsImages: options.supportsImages ?? true },
+        async *stream(request, signal) {
+            requests.push(request);
+            const index = callCount++;
+            const turn = typeof script === "function" ? script(request, index) : script[index];
+            if (!turn)
+                throw new Error(`faux script has no turn for request ${index + 1}`);
+            if (signal.aborted)
+                throw abortError();
+            if (turn.error)
+                throw turn.error;
+            if (turn.hang)
+                await waitForAbort(signal);
+            if (turn.droppedFirst) {
+                yield { type: "text_delta", delta: turn.droppedFirst };
+                yield { type: "restart" };
+            }
+            if (turn.reasoning)
+                yield { type: "reasoning_delta", delta: turn.reasoning };
+            if (turn.text)
+                for (const piece of pieces(turn.text, turn.chunkSize))
+                    yield { type: "text_delta", delta: piece };
+            let toolCount = 0;
+            for (const call of turn.toolCalls ?? []) {
+                toolCount++;
+                yield { type: "tool_call", call: { id: call.id ?? `call_${index + 1}_${toolCount}`, name: call.name, args: call.args } };
+            }
+            if (turn.truncatedToolCall) {
+                yield { type: "tool_call_truncated", id: turn.truncatedToolCall.id ?? `call_${index + 1}_cut`, name: turn.truncatedToolCall.name };
+            }
+            const output = estimateTokens([turn.text, turn.reasoning, turn.toolCalls]);
+            yield {
+                type: "usage",
+                usage: { input: estimateTokens(request.messages), output, cacheRead: 0, cacheWrite: 0, ...turn.usage },
+            };
+            const stop = turn.stop ?? (turn.truncatedToolCall ? "length" : toolCount > 0 ? "tool_use" : "stop");
+            yield { type: "done", stop };
+        },
+    };
+}

package/dist/packages/testing/src/index.d.ts

@@ -0,0 +1,4 @@
+export { createRng } from "./rng.js";
+export type { Rng } from "./rng.js";
+export { createFauxClient } from "./faux.js";
+export type { FauxClient, FauxOptions, FauxScript, FauxTurn } from "./faux.js";

package/dist/packages/testing/src/index.js

@@ -0,0 +1,2 @@
+export { createRng } from "./rng.js";
+export { createFauxClient } from "./faux.js";

package/dist/packages/testing/src/rng.d.ts

@@ -0,0 +1,7 @@
+export interface Rng {
+    next(): number;
+    int(minInclusive: number, maxInclusive: number): number;
+    pick<T>(items: readonly T[]): T;
+    chance(probability: number): boolean;
+}
+export declare function createRng(seed: number): Rng;

package/dist/packages/testing/src/rng.js

@@ -0,0 +1,17 @@
+// Small seeded random generator (mulberry32) so generated test cases are reproducible.
+export function createRng(seed) {
+    let state = seed >>> 0;
+    const next = () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    return {
+        next,
+        int: (min, max) => min + Math.floor(next() * (max - min + 1)),
+        pick: (items) => items[Math.floor(next() * items.length)],
+        chance: (probability) => next() < probability,
+    };
+}

package/dist/sdk/index.d.ts

@@ -1,10 +1,18 @@
 export { buildSystemPrompt, bundle, compose, CompositionError, corePlugins, createAgent } from "../packages/agent/src/index.js";
 export type { Agent, AgentConfig, Composable, ModelConfig } from "../packages/agent/src/index.js";
-export { createLocalEnvironment, createRemoteEnvironment } from "../packages/env/src/index.js";
-export type { RemoteRunner } from "../packages/env/src/index.js";
-export type { Content, Environment, Event, LlmClient, Plugin, RunHandle, RunResult, Tool, ToolContext, ToolResult } from "../packages/kernel/src/index.js";
+export { createLocalEnvironment, createRemoteEnvironment, createSshEnvironment, OutsideDirectoryError, RemoteConnectionError } from "../packages/env/src/index.js";
+export type { LocalOptions, RemoteRunner, SshOptions } from "../packages/env/src/index.js";
+export type { CompactionConfig, Content, ContextStatus, Decision, EntryBody, Environment, Event, EventTransform, ExecResult, FileInfo, GoalRecord, GoalStatus, HookContext, HookName, Hooks, LlmClient, LlmEvent, LlmRequest, Log, LogEntry, Message, ModelInfo, PauseReason, Plugin, PluginApi, PrepareContext, ProcessHandle, Prompts, ProviderErrorKind, Role, RunEndReason, RunHandle, RunOptions, RunResult, StopReason, ThinkingLevel, Tool, ToolCall, ToolContext, ToolDecl, ToolEffect, ToolResult, TurnInfo, Usage, UsageTotals, UserInput, } from "../packages/kernel/src/index.js";
+export { FatalHookError, ProviderError } from "../packages/kernel/src/index.js";
 export { compatPresets, createChatClient } from "../packages/llm/src/index.js";
 export type { ChatClientOptions, ChatCompat } from "../packages/llm/src/index.js";
+export { contextPlugin } from "../packages/plugins/context/src/index.js";
+export type { ContextOptions, ContextPlugin } from "../packages/plugins/context/src/index.js";
 export { limitsPlugin } from "../packages/plugins/limits/src/index.js";
+export { resiliencePlugin } from "../packages/plugins/resilience/src/index.js";
+export type { FixOptions, ResilienceOptions } from "../packages/plugins/resilience/src/index.js";
 export { redactionPlugin } from "../packages/plugins/redaction/src/index.js";
 export { reviewPlugin } from "../packages/plugins/review/src/index.js";
+export type { McpServerConfig, McpServerStatus } from "../packages/plugins/toolset/src/index.js";
+export { toolsPlugin } from "../packages/plugins/tools/src/index.js";
+export type { ToolsPluginOptions } from "../packages/plugins/tools/src/index.js";

package/dist/sdk/index.js

@@ -1,6 +1,10 @@
 export { buildSystemPrompt, bundle, compose, CompositionError, corePlugins, createAgent } from "../packages/agent/src/index.js";
-export { createLocalEnvironment, createRemoteEnvironment } from "../packages/env/src/index.js";
+export { createLocalEnvironment, createRemoteEnvironment, createSshEnvironment, OutsideDirectoryError, RemoteConnectionError } from "../packages/env/src/index.js";
+export { FatalHookError, ProviderError } from "../packages/kernel/src/index.js";
 export { compatPresets, createChatClient } from "../packages/llm/src/index.js";
+export { contextPlugin } from "../packages/plugins/context/src/index.js";
 export { limitsPlugin } from "../packages/plugins/limits/src/index.js";
+export { resiliencePlugin } from "../packages/plugins/resilience/src/index.js";
 export { redactionPlugin } from "../packages/plugins/redaction/src/index.js";
 export { reviewPlugin } from "../packages/plugins/review/src/index.js";
+export { toolsPlugin } from "../packages/plugins/tools/src/index.js";

package/dist/sdk/testing.d.ts

@@ -0,0 +1,2 @@
+export { createFauxClient } from "../packages/testing/src/index.js";
+export type { FauxClient, FauxOptions, FauxScript, FauxTurn } from "../packages/testing/src/index.js";

package/dist/sdk/testing.js

@@ -0,0 +1,2 @@
+// A scripted model for testing an application built on the SDK: the replies are written in advance, so a test needs no provider, no key and no network.
+export { createFauxClient } from "../packages/testing/src/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sakura-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "type": "module",
   "workspaces": [
@@ -55,6 +55,10 @@
     ".": {
       "types": "./dist/sdk/index.d.ts",
       "import": "./dist/sdk/index.js"
+    },
+    "./testing": {
+      "types": "./dist/sdk/testing.d.ts",
+      "import": "./dist/sdk/testing.js"
     }
   },
   "types": "./dist/sdk/index.d.ts",