@hellohelen-ai/goliath 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hellohelen-ai / David Hanlon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# Goliath
+
+**An agent harness for the phone's own model.**
+
+Apple ships a ~3B language model on every iPhone with Apple Intelligence. It is free, private, and
+fast. It also has a 4,096-token window and gets lost after a few tool calls. Goliath is the loop
+that makes it useful anyway: it plans one step at a time, runs each step in a fresh context, keeps
+tool output small, asks before it changes anything, and hands the turn to a cloud agent when the
+phone cannot finish.
+
+It only needs one stone.
+
+```ts
+import { createGoliath, defineTool } from "@hellohelen-ai/goliath";
+import { apple } from "@react-native-ai/apple";
+import { z } from "zod";
+
+const listTasks = defineTool({
+  name: "listTasks",
+  description: "The user's open tasks.",
+  parameters: z.object({}),
+  execute: () => convex.query(api.tasks.list, {}),
+});
+
+const createTask = defineTool({
+  name: "createTask",
+  description: "Add a task.",
+  parameters: z.object({ title: z.string() }),
+  writes: true, // Goliath asks before running it
+  execute: ({ title }) => convex.mutation(api.tasks.create, { title }),
+});
+
+const goliath = createGoliath({
+  model: apple(),
+  tools: { listTasks, createTask },
+  confirm: async ({ tool, input }) => askTheUser(tool, input),
+  fallback: async ({ ask, summary, steps }) => cloudAgent.turn({ ask, summary, steps }),
+});
+
+const result = await goliath.run("if I don't already have it, add call the dentist");
+result.text; // "Added Call the dentist. You now have three open tasks."
+result.handledBy; // "device" | "cloud"
+result.steps; // what it did, one line each
+```
+
+Any [AI SDK](https://ai-sdk.dev) language model works. On a phone that is
+[`@react-native-ai/apple`](https://ai-sdk.dev/providers/community-providers/react-native-apple);
+in a test it is the scripted model from `@hellohelen-ai/goliath/testing`.
+
+## How a turn runs
+
+```
+ask ──► recall ──► conductor ──► worker ──► judge ──► … ──► answer ──► remember
+            │          │            │          │
+         memory    next stone   fresh ctx   stalled?
+         brief     (JSON, 3     one tool    → fallback
+                    fields)     ≤600 chars
+```
+
+| Stage         | What it sees                                            | What it returns                                                                      |
+| ------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **Conductor** | The ask, the memory brief, and one line per step so far | `{ kind: "tool" \| "answer" \| "escalate", tool?, brief }`                           |
+| **Worker**    | A one-line brief and one tool's schema                  | The arguments, as structured output. Goliath runs the tool and compresses the result |
+| **Judge**     | The step log                                            | Escalate on a repeated call, an empty answer, or the step cap                        |
+| **Answer**    | The ask, the brief, the step log                        | Two or three sentences                                                               |
+| **Scribe**    | The last three exchanges                                | A rolling brief of at most 60 words, updated only when an exchange falls off         |
+
+Nothing a worker saw survives the step. The conductor never sees raw JSON. That is the whole trick.
+
+## Why not just call the model in a loop
+
+You can. The AI SDK's `generateText` with `stopWhen` is that loop, and Apple's own session runs a
+tool loop natively. Both fall over on a phone for the same reasons:
+
+- **The window fills.** One JSON tool result can be a thousand tokens. Three of them and the model
+  has forgotten the ask.
+- **Many tools confuse a small model.** Past about five definitions, it picks wrong or invents
+  arguments. Goliath gives each worker one.
+- **Apple runs its loop out of sight.** Under the Callstack provider, tools are pre-registered and
+  executed inside Apple's own session; the AI SDK sees one step and `stopWhen` never fires. Goliath
+  never hands tools to the provider. It asks for the arguments as structured output, which Apple's
+  guided generation constrains at decode time, then runs the tool itself.
+- **There is no confidence signal.** No logprobs on device. Goliath watches for the things a lost
+  3B model does: repeats itself, answers with nothing, runs past the cap.
+
+## What you supply
+
+| Option         | Default             | Notes                                                                      |
+| -------------- | ------------------- | -------------------------------------------------------------------------- |
+| `model`        | required            | Any AI SDK `LanguageModel`                                                 |
+| `tools`        | `{}`                | Keep to five or fewer per Goliath. Flat schemas. One-sentence descriptions |
+| `memory`       | in-process          | `{ load, save }` over `{ summary, recent }`. Persist it however you like   |
+| `fallback`     | none                | Receives the ask, the brief, the step log, and the reason. Returns text    |
+| `confirm`      | approve all         | Asked before any `writes: true` tool runs                                  |
+| `window`       | `4096`              | Apple Foundation Models. The brief is budgeted at one eighth of it         |
+| `maxSteps`     | `5`                 | Five stones                                                                |
+| `instructions` | a careful assistant | One or two sentences. Every prompt starts with it                          |
+| `onEvent`      | none                | Every trace event as it happens: plan, tool, confirm, escalate, remember   |
+
+## Testing without a phone
+
+```ts
+import { fakeModel } from "@hellohelen-ai/goliath/testing";
+
+const model = fakeModel([
+  { json: { kind: "tool", tool: "listTasks", brief: "see what is open" } },
+  { toolCall: { name: "listTasks", input: {} } },
+  { json: { kind: "answer", brief: "reply" } },
+  { text: "You have two tasks: buy milk and call mom." },
+]);
+```
+
+The script is consumed in order and a test fails if it runs out, so a passing test proves the
+harness sent exactly the prompts you expected. `model.calls` holds every prompt for assertions.
+
+## Evals
+
+`evals/fixtures.ts` holds the asks a personal assistant hears every day, with the tool calls a good
+run makes and where it should finish. `runEvals` scores any model against them and prints the
+split:
+
+```
+PASS  list-today         device    412ms
+PASS  add-task           device    655ms
+PASS  add-after-check    device   1203ms
+PASS  small-talk         device    198ms
+PASS  plan-week          cloud     301ms
+
+5/5 passed · 4 on device · 1 escalated
+```
+
+That last line is the number this project exists for.
+
+## Status
+
+Early. The core loop, compression, memory, judge, and eval runner are here and tested against a
+scripted model. On-device runs and the Apple provider adapter are next. See `docs/` for the
+research behind the design.
+
+## License
+
+MIT

package/dist/budget.d.ts

@@ -0,0 +1,16 @@
+import type { ModelMessage } from "ai";
+/**
+ * Tokens, estimated without a tokenizer. English runs near four characters
+ * per token; the margin covers code, names, and JSON, which run denser.
+ */
+declare const estimateTokens: (text: string) => number;
+declare const textOf: (message: ModelMessage) => string;
+declare const messageTokens: (message: ModelMessage) => number;
+declare const transcriptTokens: (messages: ModelMessage[]) => number;
+/**
+ * Drop the oldest non-system messages until the transcript fits. The first
+ * message survives when it is the system prompt; the last always survives.
+ */
+declare const fitWithin: (messages: ModelMessage[], budget: number) => ModelMessage[];
+export { estimateTokens, fitWithin, messageTokens, textOf, transcriptTokens };
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAEvC;;;GAGG;AACH,QAAA,MAAM,cAAc,GAAI,MAAM,MAAM,KAAG,MAA6C,CAAC;AAErF,QAAA,MAAM,MAAM,GAAI,SAAS,YAAY,KAAG,MAUvC,CAAC;AAEF,QAAA,MAAM,aAAa,GAAI,SAAS,YAAY,KAAG,MAA6C,CAAC;AAE7F,QAAA,MAAM,gBAAgB,GAAI,UAAU,YAAY,EAAE,KAAG,MACe,CAAC;AAErE;;;GAGG;AACH,QAAA,MAAM,SAAS,GAAI,UAAU,YAAY,EAAE,EAAE,QAAQ,MAAM,KAAG,YAAY,EAOzE,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/budget.js

@@ -0,0 +1,36 @@
+/**
+ * Tokens, estimated without a tokenizer. English runs near four characters
+ * per token; the margin covers code, names, and JSON, which run denser.
+ */
+const estimateTokens = (text) => Math.ceil((text.length / 4) * 1.15);
+const textOf = (message) => {
+    if (typeof message.content === "string")
+        return message.content;
+    return message.content
+        .map((part) => {
+        if (part.type === "text")
+            return part.text;
+        if (part.type === "tool-call")
+            return JSON.stringify(part.input ?? {});
+        if (part.type === "tool-result")
+            return JSON.stringify(part.output ?? "");
+        return "";
+    })
+        .join(" ");
+};
+const messageTokens = (message) => estimateTokens(textOf(message)) + 4;
+const transcriptTokens = (messages) => messages.reduce((sum, message) => sum + messageTokens(message), 0);
+/**
+ * Drop the oldest non-system messages until the transcript fits. The first
+ * message survives when it is the system prompt; the last always survives.
+ */
+const fitWithin = (messages, budget) => {
+    const kept = [...messages];
+    const protectedHead = kept[0]?.role === "system" ? 1 : 0;
+    while (transcriptTokens(kept) > budget && kept.length > protectedHead + 1) {
+        kept.splice(protectedHead, 1);
+    }
+    return kept;
+};
+export { estimateTokens, fitWithin, messageTokens, textOf, transcriptTokens };
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,cAAc,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAErF,MAAM,MAAM,GAAG,CAAC,OAAqB,EAAU,EAAE;IAC/C,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC;IAChE,OAAO,OAAO,CAAC,OAAO;SACnB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;QAC3C,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW;YAAE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QACvE,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAC1E,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC,CAAC;AAEF,MAAM,aAAa,GAAG,CAAC,OAAqB,EAAU,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC;AAE7F,MAAM,gBAAgB,GAAG,CAAC,QAAwB,EAAU,EAAE,CAC5D,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;AAErE;;;GAGG;AACH,MAAM,SAAS,GAAG,CAAC,QAAwB,EAAE,MAAc,EAAkB,EAAE;IAC7E,MAAM,IAAI,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IAC3B,MAAM,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,OAAO,gBAAgB,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,MAAM,GAAG,aAAa,GAAG,CAAC,EAAE,CAAC;QAC1E,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/compress/structural.d.ts

@@ -0,0 +1,4 @@
+declare const clip: (text: string, max: number) => string;
+declare const summarizeToolResult: (value: unknown, maxChars?: number) => string;
+export { summarizeToolResult, clip };
+//# sourceMappingURL=structural.d.ts.map

package/dist/compress/structural.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural.d.ts","sourceRoot":"","sources":["../../src/compress/structural.ts"],"names":[],"mappings":"AAcA,QAAA,MAAM,IAAI,GAAI,MAAM,MAAM,EAAE,KAAK,MAAM,KAAG,MAC0B,CAAC;AAyBrE,QAAA,MAAM,mBAAmB,GAAI,OAAO,OAAO,EAAE,iBAA4B,KAAG,MA2B3E,CAAC;AAEF,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC"}

package/dist/compress/structural.js

@@ -0,0 +1,68 @@
+/**
+ * Turn a tool result into the fewest characters the model still needs.
+ * JSON becomes `key: value` lines, arrays become numbered lines, long
+ * strings get cut. No model call, so this runs on every result.
+ */
+const DEFAULT_MAX_CHARS = 600;
+/** Long lists show the first items, a count, and the last items (deepagents, Grok Bot). */
+const HEAD_ITEMS = 5;
+const TAIL_ITEMS = 2;
+const MAX_ITEMS = HEAD_ITEMS + TAIL_ITEMS;
+const MAX_VALUE_CHARS = 80;
+/** A line that looks like a failure survives any cut (OpenClaw's diagnostic tail). */
+const ERROR_LINE = /\b(error|exception|failed|fatal|denied|timed?\s?out)\b/i;
+const clip = (text, max) => text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
+const scalar = (value) => {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return clip(value, MAX_VALUE_CHARS);
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return "";
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const lineFor = (value) => {
+    if (isRecord(value)) {
+        return Object.entries(value)
+            .map(([key, item]) => {
+            const text = scalar(item);
+            return text ? `${key}: ${text}` : "";
+        })
+            .filter(Boolean)
+            .join(", ");
+    }
+    return scalar(value);
+};
+const summarizeToolResult = (value, maxChars = DEFAULT_MAX_CHARS) => {
+    if (value === undefined || value === null)
+        return "done";
+    if (typeof value === "string")
+        return value.trim() ? clip(value, maxChars) : "(no output)";
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return "none";
+        const line = (item, i) => `${i + 1}. ${lineFor(item)}`;
+        if (value.length <= MAX_ITEMS)
+            return clip(value.map(line).join("\n"), maxChars);
+        const head = value.slice(0, HEAD_ITEMS).map(line);
+        const tail = value
+            .slice(-TAIL_ITEMS)
+            .map((item, i) => line(item, value.length - TAIL_ITEMS + i));
+        const omitted = value
+            .slice(HEAD_ITEMS, -TAIL_ITEMS)
+            .map((item, i) => line(item, HEAD_ITEMS + i))
+            .filter((text) => ERROR_LINE.test(text));
+        const shown = [...head, `… ${value.length - MAX_ITEMS} omitted`, ...omitted, ...tail];
+        return clip(shown.join("\n"), maxChars);
+    }
+    if (isRecord(value)) {
+        const lines = Object.entries(value).map(([key, item]) => Array.isArray(item) || isRecord(item)
+            ? `${key}: ${lineFor(item) || summarizeToolResult(item, MAX_VALUE_CHARS)}`
+            : `${key}: ${scalar(item)}`);
+        return clip(lines.join("\n"), maxChars);
+    }
+    return clip(String(value), maxChars);
+};
+export { summarizeToolResult, clip };
+//# sourceMappingURL=structural.js.map

package/dist/compress/structural.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural.js","sourceRoot":"","sources":["../../src/compress/structural.ts"],"names":[],"mappings":"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"}

package/dist/conductor.d.ts

@@ -0,0 +1,75 @@
+import { type LanguageModel } from "ai";
+import { z } from "zod";
+import type { PlanExample, StepRecord, ToolMap, TraceEvent } from "./types.js";
+declare const planSchema: z.ZodObject<{
+    why: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<{
+        tool: "tool";
+        answer: "answer";
+        escalate: "escalate";
+    }>;
+    tool: z.ZodOptional<z.ZodString>;
+    brief: z.ZodString;
+}, z.core.$strip>;
+type Plan = z.infer<typeof planSchema>;
+/**
+ * The same shape with `tool` as an enum of the registered names. Under
+ * constrained decoding an enum cannot be misspelled or invented (Apple's
+ * guarantee only holds when the name is in the schema).
+ */
+declare const planSchemaFor: (toolNames: string[]) => z.ZodObject<{
+    why: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<{
+        tool: "tool";
+        answer: "answer";
+        escalate: "escalate";
+    }>;
+    tool: z.ZodOptional<z.ZodString>;
+    brief: z.ZodString;
+}, z.core.$strip> | z.ZodObject<{
+    why: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<{
+        tool: "tool";
+        answer: "answer";
+        escalate: "escalate";
+    }>;
+    tool: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
+    brief: z.ZodString;
+}, z.core.$strip>;
+type PlanOutcome = {
+    ok: true;
+    plan: Plan;
+} | {
+    ok: false;
+    reason: "plan-invalid" | "no-such-tool";
+    hint: string;
+};
+/**
+ * Apple's window is input plus output, and the overflow error kills the
+ * session, so the conductor's prompt must stay well under it. Past this share
+ * of the window, older step results are clipped to a line before prompting.
+ */
+declare const PROMPT_SHARE = 0.7;
+declare const trimSteps: (steps: StepRecord[]) => StepRecord[];
+/** Ask the model what to do next, with only the ask, the brief, and the step log in view. */
+declare const plan: (input: {
+    model: LanguageModel;
+    instructions: string;
+    tools: ToolMap;
+    ask: string;
+    summary: string;
+    steps: StepRecord[];
+    maxSteps: number;
+    window: number;
+    emit?: (event: TraceEvent) => void;
+    /** Why the previous plan was rejected, fed back on the one retry. */
+    retryHint?: string;
+    facts?: Record<string, string>;
+    examples?: PlanExample[];
+    signal?: AbortSignal;
+}) => Promise<PlanOutcome>;
+export { plan, planSchema, planSchemaFor, trimSteps, PROMPT_SHARE };
+export type { Plan, PlanOutcome };
+//# sourceMappingURL=conductor.d.ts.map

package/dist/conductor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conductor.d.ts","sourceRoot":"","sources":["../src/conductor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgD,KAAK,aAAa,EAAE,MAAM,IAAI,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAc/E,QAAA,MAAM,UAAU;;;;;;;;;iBAKd,CAAC;AAEH,KAAK,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEvC;;;;GAIG;AACH,QAAA,MAAM,aAAa,GAAI,WAAW,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;iBAQ1B,CAAC;AAEjB,KAAK,WAAW,GACd;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAUlG;;;;GAIG;AACH,QAAA,MAAM,YAAY,MAAM,CAAC;AAGzB,QAAA,MAAM,SAAS,GAAI,OAAO,UAAU,EAAE,KAAG,UAAU,EAKhD,CAAC;AAEJ,6FAA6F;AAC7F,QAAA,MAAM,IAAI,GAAU,OAAO;IACzB,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACnC,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAG,OAAO,CAAC,WAAW,CA+CtB,CAAC;AAEF,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;AACpE,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC"}

package/dist/conductor.js

@@ -0,0 +1,102 @@
+import { NoObjectGeneratedError, Output, generateText } from "ai";
+import { z } from "zod";
+import { estimateTokens } from "./budget.js";
+import { clip } from "./compress/structural.js";
+import { conductorSystem, conductorUser } from "./prompts.js";
+/**
+ * The next stone. Flat on purpose: three fields is what a 3B model fills in
+ * reliably under constrained decoding.
+ */
+/**
+ * Field order is generation order under guided generation, so `why` comes
+ * first: a rationale before the decision is worth ~10 points at this model
+ * size (docs/research/round2/small-model-prompting.md § 2.1). It is one
+ * short sentence naming the fact that decides the step, not deliberation.
+ */
+const WHY = "One short sentence naming the fact that decides this step.";
+const planSchema = z.object({
+    why: z.string().optional().describe(WHY),
+    kind: z.enum(["tool", "answer", "escalate"]),
+    tool: z.string().optional(),
+    brief: z.string(),
+});
+/**
+ * The same shape with `tool` as an enum of the registered names. Under
+ * constrained decoding an enum cannot be misspelled or invented (Apple's
+ * guarantee only holds when the name is in the schema).
+ */
+const planSchemaFor = (toolNames) => toolNames.length
+    ? z.object({
+        why: z.string().optional().describe(WHY),
+        kind: z.enum(["tool", "answer", "escalate"]),
+        tool: z.enum(toolNames).optional(),
+        brief: z.string(),
+    })
+    : planSchema;
+const planInvalidHint = (toolNames) => toolNames.length
+    ? `Your last reply was not valid. Reply with JSON fields kind, tool, brief. tool must be one of: ${toolNames.join(", ")}, or leave it out and answer.`
+    : "Your last reply was not valid. Reply with JSON fields kind, tool, brief.";
+const noSuchToolHint = (name, toolNames) => `No such tool available: ${name ?? "(none)"}. Pick one of: ${toolNames.join(", ")}, or answer.`;
+/**
+ * Apple's window is input plus output, and the overflow error kills the
+ * session, so the conductor's prompt must stay well under it. Past this share
+ * of the window, older step results are clipped to a line before prompting.
+ */
+const PROMPT_SHARE = 0.7;
+const CLIPPED_RESULT_CHARS = 100;
+const trimSteps = (steps) => steps.map((step, i) => step.kind === "tool" && step.result && i < steps.length - 1
+    ? { ...step, result: clip(step.result.split("\n")[0] ?? "", CLIPPED_RESULT_CHARS) }
+    : step);
+/** Ask the model what to do next, with only the ask, the brief, and the step log in view. */
+const plan = async (input) => {
+    const toolNames = Object.keys(input.tools);
+    const system = conductorSystem(input.instructions, input.tools, input.maxSteps, {
+        ...(input.facts ? { facts: input.facts } : {}),
+        ...(input.examples ? { examples: input.examples } : {}),
+    });
+    const limit = Math.floor(input.window * PROMPT_SHARE);
+    let steps = input.steps;
+    const render = (log) => {
+        const base = conductorUser({
+            ask: input.ask,
+            summary: input.summary,
+            steps: log,
+            maxSteps: input.maxSteps,
+        });
+        return input.retryHint ? `${base}\n\n${input.retryHint}` : base;
+    };
+    let prompt = render(steps);
+    let tokens = estimateTokens(system) + estimateTokens(prompt);
+    if (tokens > limit) {
+        steps = trimSteps(steps);
+        prompt = render(steps);
+        tokens = estimateTokens(system) + estimateTokens(prompt);
+        input.emit?.({ type: "budget", label: "conductor", tokens, limit });
+    }
+    try {
+        const result = await generateText({
+            model: input.model,
+            output: Output.object({ schema: planSchemaFor(toolNames) }),
+            system,
+            prompt,
+            ...(input.signal ? { abortSignal: input.signal } : {}),
+        });
+        const next = result.output;
+        if (!next)
+            return { ok: false, reason: "plan-invalid", hint: planInvalidHint(toolNames) };
+        if (next.kind === "tool" && (!next.tool || !toolNames.includes(next.tool))) {
+            return { ok: false, reason: "no-such-tool", hint: noSuchToolHint(next.tool, toolNames) };
+        }
+        return { ok: true, plan: next };
+    }
+    catch (error) {
+        // Only a malformed plan is the model's mistake to retry. Guardrails, a dead
+        // session, or an unavailable model propagate so the turn escalates as model-error.
+        if (NoObjectGeneratedError.isInstance(error)) {
+            return { ok: false, reason: "plan-invalid", hint: planInvalidHint(toolNames) };
+        }
+        throw error;
+    }
+};
+export { plan, planSchema, planSchemaFor, trimSteps, PROMPT_SHARE };
+//# sourceMappingURL=conductor.js.map

package/dist/conductor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conductor.js","sourceRoot":"","sources":["../src/conductor.ts"],"names":[],"mappings":"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"}

package/dist/create-goliath.d.ts

@@ -0,0 +1,22 @@
+import type { GoliathConfig, RunResult, TraceEvent } from "./types.js";
+declare const DEFAULT_WINDOW = 4096;
+declare const DEFAULT_MAX_STEPS = 5;
+/** Consecutive model errors before the rest of the session skips the device. */
+declare const SESSION_FALLBACK_AFTER = 3;
+type RunOptions = {
+    signal?: AbortSignal;
+    onEvent?: (event: TraceEvent) => void;
+};
+type Goliath = {
+    run: (ask: string, options?: RunOptions) => Promise<RunResult>;
+    /** True once three turns in a row died on the device; later turns go straight to the cloud. */
+    readonly sessionFallback: boolean;
+};
+/**
+ * Build a Goliath. Give it a model, the tools the app allows, somewhere to
+ * remember, and somewhere to send what the phone cannot finish.
+ */
+declare const createGoliath: (config: GoliathConfig) => Goliath;
+export { createGoliath, DEFAULT_MAX_STEPS, DEFAULT_WINDOW, SESSION_FALLBACK_AFTER };
+export type { Goliath, RunOptions };
+//# sourceMappingURL=create-goliath.d.ts.map

package/dist/create-goliath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-goliath.d.ts","sourceRoot":"","sources":["../src/create-goliath.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvE,QAAA,MAAM,cAAc,OAAO,CAAC;AAC5B,QAAA,MAAM,iBAAiB,IAAI,CAAC;AAC5B,gFAAgF;AAChF,QAAA,MAAM,sBAAsB,IAAI,CAAC;AAEjC,KAAK,UAAU,GAAG;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CACvC,CAAC;AAEF,KAAK,OAAO,GAAG;IACb,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/D,+FAA+F;IAC/F,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC,CAAC;AAEF;;;GAGG;AACH,QAAA,MAAM,aAAa,GAAI,QAAQ,aAAa,KAAG,OA6D9C,CAAC;AAEF,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,CAAC;AACpF,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/create-goliath.js

@@ -0,0 +1,68 @@
+import { inMemory } from "./memory/in-memory.js";
+import { runTurn } from "./run-turn.js";
+const DEFAULT_WINDOW = 4096;
+const DEFAULT_MAX_STEPS = 5;
+/** Consecutive model errors before the rest of the session skips the device. */
+const SESSION_FALLBACK_AFTER = 3;
+/**
+ * Build a Goliath. Give it a model, the tools the app allows, somewhere to
+ * remember, and somewhere to send what the phone cannot finish.
+ */
+const createGoliath = (config) => {
+    const memory = config.memory ?? inMemory();
+    const confirm = config.confirm ?? (async () => true);
+    // The conductor picks by name, so the map is keyed by each tool's own name,
+    // whatever the app called the property.
+    const tools = Object.fromEntries(Object.values(config.tools ?? {}).map((tool) => [tool.name, tool]));
+    let consecutiveModelErrors = 0;
+    const goliath = {
+        get sessionFallback() {
+            return consecutiveModelErrors >= SESSION_FALLBACK_AFTER;
+        },
+        run: async (ask, options = {}) => {
+            const emit = (event) => {
+                config.onEvent?.(event);
+                options.onEvent?.(event);
+            };
+            if (goliath.sessionFallback && config.fallback) {
+                // Claude Code switches models after three consecutive overloads. A
+                // device that has failed three turns running is not coming back this
+                // session; stop paying the on-device latency to find out.
+                const state = await memory.load();
+                emit({ type: "escalate", reason: "model-error", error: "session fallback" });
+                const { text } = await config.fallback({
+                    ask,
+                    summary: state.summary,
+                    recent: state.recent,
+                    steps: [],
+                    reason: "model-error",
+                    error: "session fallback",
+                    ...(options.signal ? { signal: options.signal } : {}),
+                });
+                return { text, handledBy: "cloud", steps: [], trace: [] };
+            }
+            const facts = typeof config.facts === "function" ? config.facts() : config.facts;
+            const result = await runTurn({
+                ask,
+                model: config.model,
+                tools,
+                memory,
+                confirm,
+                ...(facts ? { facts } : {}),
+                ...(config.examples ? { examples: config.examples } : {}),
+                ...(config.fallback ? { fallback: config.fallback } : {}),
+                ...(config.instructions ? { instructions: config.instructions } : {}),
+                maxSteps: config.maxSteps ?? DEFAULT_MAX_STEPS,
+                window: config.window ?? DEFAULT_WINDOW,
+                onEvent: emit,
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+            const diedOnDevice = result.trace.some((e) => e.type === "escalate" && e.reason === "model-error");
+            consecutiveModelErrors = diedOnDevice ? consecutiveModelErrors + 1 : 0;
+            return result;
+        },
+    };
+    return goliath;
+};
+export { createGoliath, DEFAULT_MAX_STEPS, DEFAULT_WINDOW, SESSION_FALLBACK_AFTER };
+//# sourceMappingURL=create-goliath.js.map

package/dist/create-goliath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-goliath.js","sourceRoot":"","sources":["../src/create-goliath.ts"],"names":[],"mappings":"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"}

package/dist/fallback/http-fallback.d.ts

@@ -0,0 +1,20 @@
+import type { Fallback, FallbackRequest } from "../types.js";
+type HttpFallbackOptions = {
+    url: string;
+    /** Static headers, or a function when the token rotates. */
+    headers?: Record<string, string> | (() => Promise<Record<string, string>>);
+    /** Override for tests. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Pull the answer text out of the response body. Default reads `{ text }`. */
+    readText?: (body: unknown) => string;
+};
+type FallbackPayload = Omit<FallbackRequest, "signal">;
+/**
+ * Send the turn to a server as JSON and read back `{ text }`. The payload is
+ * exactly what the conductor saw, so the cloud agent starts where the phone
+ * stopped instead of from scratch.
+ */
+declare const httpFallback: (options: HttpFallbackOptions) => Fallback;
+export { httpFallback };
+export type { FallbackPayload, HttpFallbackOptions };
+//# sourceMappingURL=http-fallback.d.ts.map

package/dist/fallback/http-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-fallback.d.ts","sourceRoot":"","sources":["../../src/fallback/http-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7D,KAAK,mBAAmB,GAAG;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3E,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;CACtC,CAAC;AAEF,KAAK,eAAe,GAAG,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;AAEvD;;;;GAIG;AACH,QAAA,MAAM,YAAY,GAAI,SAAS,mBAAmB,KAAG,QAoBpD,CAAC;AAUF,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC"}