@hellohelen-ai/goliath 0.0.1

package/dist/types.d.ts

@@ -0,0 +1,182 @@
+import type { LanguageModel, ModelMessage } from "ai";
+import type { z } from "zod";
+/**
+ * A tool the phone's model may call. Keep the schema flat and the
+ * description one sentence: a 3B model reads every word of it on every step.
+ */
+type GoliathTool<INPUT = unknown, OUTPUT = unknown> = {
+    name: string;
+    description: string;
+    parameters: z.ZodType<INPUT>;
+    /** True when the tool changes something. Goliath asks before running it. */
+    writes?: boolean;
+    execute: (input: INPUT, context: ToolContext) => Promise<OUTPUT> | OUTPUT;
+    /**
+     * What the model sees. The app keeps the full output; the model gets this
+     * string. Default: `key: value` lines capped at 600 characters.
+     */
+    toModelOutput?: (output: OUTPUT) => string;
+    /**
+     * Tools that must have run earlier in the turn. Rendered to the conductor
+     * as "Use lookupContact before sendMessage." TinyAgent's biggest plan-shape
+     * lever was exactly this sentence.
+     */
+    requires?: string[];
+};
+type ToolContext = {
+    signal?: AbortSignal;
+};
+type ToolMap = Record<string, GoliathTool<any, any>>;
+/** What Goliath remembers between turns. Small on purpose. */
+type MemoryState = {
+    /** A rolling brief of everything that came before, written by the scribe. */
+    summary: string;
+    /** The last few exchanges, verbatim, newest last. */
+    recent: Exchange[];
+};
+type Exchange = {
+    ask: string;
+    answer: string;
+    at: number;
+};
+type Memory = {
+    load: () => Promise<MemoryState>;
+    save: (state: MemoryState) => Promise<void>;
+};
+/** Where a turn goes when the phone cannot finish it. */
+type Fallback = (request: FallbackRequest) => Promise<{
+    text: string;
+}>;
+type FallbackRequest = {
+    ask: string;
+    summary: string;
+    recent: Exchange[];
+    steps: StepRecord[];
+    reason: EscalationReason;
+    /** The model or provider error message, when `reason` is "model-error". */
+    error?: string;
+    signal?: AbortSignal;
+};
+type EscalationReason = "no-model" | "model-unavailable" | "too-many-steps" | "repeated-tool-call" | "empty-answer" | "plan-invalid" | "conductor-asked" | "tool-args-invalid" | "tool-error" | "guardrail" | "model-error";
+/** One stone thrown: what the conductor decided and what the worker did. */
+type StepRecord = {
+    index: number;
+    kind: "tool" | "answer";
+    brief: string;
+    tool?: string;
+    input?: unknown;
+    /** The compressed tool result the transcript carries forward. */
+    result?: string;
+    skipped?: boolean;
+    /** Served from an earlier identical step; nothing ran. */
+    cached?: boolean;
+    /** The tool threw. `result` carries the message the conductor plans around. */
+    failed?: boolean;
+    text?: string;
+};
+type ConfirmDecision = boolean | {
+    approved: boolean;
+    reason?: string;
+};
+/** Asked before a tool that writes runs. A reason on a decline reaches the conductor. */
+type Confirm = (request: {
+    tool: string;
+    input: unknown;
+    brief: string;
+}) => Promise<ConfirmDecision>;
+type TraceEvent = {
+    type: "recall";
+    summary: string;
+    recent: number;
+} | {
+    type: "plan";
+    index: number;
+    kind: StepRecord["kind"];
+    tool?: string;
+    /** The conductor's one-sentence rationale, when it gave one. */
+    why?: string;
+    brief: string;
+} | {
+    type: "confirm";
+    tool: string;
+    approved: boolean;
+    reason?: string;
+} | {
+    type: "tool";
+    tool: string;
+    input: unknown;
+    result: string;
+    ms: number;
+} | {
+    type: "answer";
+    text: string;
+} | {
+    type: "escalate";
+    reason: EscalationReason;
+    error?: string;
+} | {
+    type: "remember";
+    summary: string;
+} | {
+    type: "budget";
+    label: string;
+    tokens: number;
+    limit: number;
+};
+type RunResult = {
+    text: string;
+    handledBy: "device" | "cloud";
+    /** True when the loop stalled, no fallback was configured, and the answer is a best effort from the step log. */
+    bestEffort?: boolean;
+    steps: StepRecord[];
+    trace: TraceEvent[];
+};
+type Compressor = (input: {
+    messages: ModelMessage[];
+    ask: string;
+    budget: number;
+}) => Promise<ModelMessage[]> | ModelMessage[];
+type GoliathConfig = {
+    /** Any AI SDK language model. On a phone, `apple()` from `@react-native-ai/apple`. */
+    model: LanguageModel;
+    tools?: ToolMap;
+    memory?: Memory;
+    fallback?: Fallback;
+    /** Asked before any tool with `writes: true` runs. Default approves everything. */
+    confirm?: Confirm;
+    /** Context window in tokens. Apple Foundation Models: 4096. */
+    window?: number;
+    /** Most stones the conductor may throw in one turn. Default 5. */
+    maxSteps?: number;
+    /** Extra compressors run after the built-in structural pass. */
+    compressors?: Compressor[];
+    /** Who Goliath is, in one or two short sentences. Every prompt starts with it. */
+    instructions?: string;
+    /** Called for every trace event as it happens. */
+    onEvent?: (event: TraceEvent) => void;
+    /**
+     * Values the model should always have, injected as `key: value` lines
+     * instead of fetched by a tool (Apple TN3193: run the tool before the model
+     * when it always needs the result). Today's date, timezone, the user's name.
+     * A function is called once per turn.
+     */
+    facts?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Two or three worked plans, shown to the conductor. Format is fixed by
+     * guided generation; examples buy tool choice and ordering. Measure before
+     * keeping any: each costs ~60 tokens per step.
+     */
+    examples?: PlanExample[];
+};
+type PlanExample = {
+    ask: string;
+    /** The steps a good run takes, in order, with `answer` last. */
+    steps: Array<{
+        tool: string;
+        brief: string;
+    } | {
+        answer: string;
+    }>;
+};
+export type { Compressor, Confirm, ConfirmDecision, EscalationReason, Exchange, Fallback, FallbackRequest, GoliathConfig, GoliathTool, Memory, MemoryState, PlanExample, RunResult, StepRecord, ToolContext, ToolMap, TraceEvent, };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/worker.d.ts

@@ -0,0 +1,53 @@
+import { type LanguageModel } from "ai";
+import { z } from "zod";
+import type { Confirm, GoliathTool, StepRecord } from "./types.js";
+type ToolStepOutcome = {
+    ok: true;
+    input: unknown;
+    result: string;
+    skipped: boolean;
+    failed?: boolean;
+} | {
+    ok: false;
+    reason: "tool-args-invalid";
+};
+/**
+ * A worker gets a fresh context, one tool, and a one-line brief. The conductor
+ * already chose the tool, so the worker's whole job is the arguments: one
+ * structured-output call, then Goliath runs the tool itself.
+ *
+ * Goliath never hands tools to the provider. On Apple's runtime the provider
+ * would run its own loop with pre-registered tools and no step boundary
+ * (docs/research/rn-providers-and-ai-sdk.md § 1.3), and mixing tools with
+ * schema-constrained output suppresses tool calls on small models
+ * (docs/research/small-context-agent-patterns.md, rule 9). Asking for the
+ * arguments as a plain object sidesteps both, works on every provider, and
+ * keeps the confirm step in Goliath's hands.
+ */
+declare const runToolStep: (input: {
+    model: LanguageModel;
+    instructions: string;
+    tool: GoliathTool<any, any>;
+    brief: string;
+    ask: string;
+    confirm: Confirm;
+    signal?: AbortSignal;
+}) => Promise<ToolStepOutcome>;
+/** A tool with no parameters needs no model call at all. Apple says the same: run it directly. */
+declare const needsArguments: (schema: z.ZodType) => boolean;
+/** The closing stone: turn the step log into two or three sentences. */
+declare const runAnswerStep: (input: {
+    model: LanguageModel;
+    instructions: string;
+    ask: string;
+    summary: string;
+    steps: StepRecord[];
+    /** Appended on the one retry after an empty answer. */
+    nudge?: string;
+    /** The loop stalled; say what was found and what is open. */
+    bestEffort?: boolean;
+    signal?: AbortSignal;
+}) => Promise<string>;
+export { needsArguments, runAnswerStep, runToolStep };
+export type { ToolStepOutcome };
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgD,KAAK,aAAa,EAAE,MAAM,IAAI,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAe,MAAM,YAAY,CAAC;AAEhF,KAAK,eAAe,GAChB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAChF;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,QAAA,MAAM,WAAW,GAAU,OAAO;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAG,OAAO,CAAC,eAAe,CAyE1B,CAAC;AAEF,kGAAkG;AAClG,QAAA,MAAM,cAAc,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAC8B,CAAC;AAkB3E,wEAAwE;AACxE,QAAA,MAAM,aAAa,GAAU,OAAO;IAClC,KAAK,EAAE,aAAa,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAG,OAAO,CAAC,MAAM,CAWjB,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/worker.js

@@ -0,0 +1,124 @@
+import { NoObjectGeneratedError, Output, generateText } from "ai";
+import { z } from "zod";
+import { clip, summarizeToolResult } from "./compress/structural.js";
+import { answerSystem, answerUser, bestEffortSystem, workerSystem } from "./prompts.js";
+/**
+ * A worker gets a fresh context, one tool, and a one-line brief. The conductor
+ * already chose the tool, so the worker's whole job is the arguments: one
+ * structured-output call, then Goliath runs the tool itself.
+ *
+ * Goliath never hands tools to the provider. On Apple's runtime the provider
+ * would run its own loop with pre-registered tools and no step boundary
+ * (docs/research/rn-providers-and-ai-sdk.md § 1.3), and mixing tools with
+ * schema-constrained output suppresses tool calls on small models
+ * (docs/research/small-context-agent-patterns.md, rule 9). Asking for the
+ * arguments as a plain object sidesteps both, works on every provider, and
+ * keeps the confirm step in Goliath's hands.
+ */
+const runToolStep = async (input) => {
+    let args = {};
+    if (needsArguments(input.tool.parameters)) {
+        try {
+            const result = await generateText({
+                model: input.model,
+                output: Output.object({ schema: withMissing(input.tool.parameters) }),
+                system: workerSystem(input.instructions, input.brief),
+                prompt: input.ask,
+                ...(input.signal ? { abortSignal: input.signal } : {}),
+            });
+            if (result.output === undefined)
+                return { ok: false, reason: "tool-args-invalid" };
+            const { missing, ...rest } = result.output;
+            if (missing && missing.trim()) {
+                // The worker said what it did not have instead of inventing it. The
+                // conductor reads this like any other result and can ask the user.
+                return {
+                    ok: true,
+                    input: rest,
+                    result: `missing: ${clip(missing.trim(), 120)}. Ask the user or use another tool.`,
+                    skipped: true,
+                };
+            }
+            args = rest;
+        }
+        catch (error) {
+            // Bad JSON or a schema miss is the model's mistake; anything else is a real error.
+            if (NoObjectGeneratedError.isInstance(error))
+                return { ok: false, reason: "tool-args-invalid" };
+            throw error;
+        }
+    }
+    if (input.tool.writes) {
+        const decision = await input.confirm({
+            tool: input.tool.name,
+            input: args,
+            brief: input.brief,
+        });
+        const approved = typeof decision === "boolean" ? decision : decision.approved;
+        if (!approved) {
+            const reason = typeof decision === "object" && decision.reason ? `: ${decision.reason}` : "";
+            // Named like deepagents' rejection message so the model reads it as a
+            // decision, not an error to work around.
+            return {
+                ok: true,
+                input: args,
+                result: `declined by the user${reason}. Do not retry unless asked.`,
+                skipped: true,
+            };
+        }
+    }
+    const context = input.signal ? { signal: input.signal } : {};
+    let output;
+    try {
+        output = await input.tool.execute(args, context);
+    }
+    catch (error) {
+        if (error?.name === "AbortError")
+            throw error;
+        // smolagents: "Error executing tool ... Please try again or use another tool".
+        // The conductor reads this and plans around it; two in a row is a real signal.
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: true,
+            input: args,
+            result: `error: ${clip(message, 160)}. Try different arguments or another tool.`,
+            skipped: false,
+            failed: true,
+        };
+    }
+    const shaped = input.tool.toModelOutput
+        ? input.tool.toModelOutput(output)
+        : summarizeToolResult(output);
+    return { ok: true, input: args, result: shaped, skipped: false };
+};
+/** A tool with no parameters needs no model call at all. Apple says the same: run it directly. */
+const needsArguments = (schema) => !(schema instanceof z.ZodObject) || Object.keys(schema.shape).length > 0;
+/**
+ * The tool's schema plus a trailing optional `missing`. Last, so it cannot
+ * steal the argument budget; present, so a required value the brief did not
+ * contain is named rather than invented (the Constraint Tax's "wrong but
+ * valid" outputs are exactly invented values).
+ */
+const withMissing = (schema) => schema instanceof z.ZodObject
+    ? schema.extend({
+        missing: z
+            .string()
+            .optional()
+            .describe("Required values the brief did not contain, if any. Otherwise leave empty."),
+    })
+    : schema;
+/** The closing stone: turn the step log into two or three sentences. */
+const runAnswerStep = async (input) => {
+    const prompt = answerUser({ ask: input.ask, summary: input.summary, steps: input.steps });
+    const result = await generateText({
+        model: input.model,
+        system: input.bestEffort
+            ? bestEffortSystem(input.instructions)
+            : answerSystem(input.instructions),
+        prompt: input.nudge ? `${prompt}\n\n${input.nudge}` : prompt,
+        ...(input.signal ? { abortSignal: input.signal } : {}),
+    });
+    return result.text.trim();
+};
+export { needsArguments, runAnswerStep, runToolStep };
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

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

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@hellohelen-ai/goliath",
+  "version": "0.0.1",
+  "description": "An agent harness for the phone's own model. Apple Foundation Models, a 4k window, one stone.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hellohelen-ai/goliath.git"
+  },
+  "homepage": "https://github.com/hellohelen-ai/goliath#readme",
+  "bugs": "https://github.com/hellohelen-ai/goliath/issues",
+  "keywords": [
+    "on-device",
+    "agent",
+    "apple-intelligence",
+    "foundation-models",
+    "react-native",
+    "expo",
+    "ai-sdk",
+    "small-language-model"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "bun run typecheck && bun run format:check && bun run test && bun run build",
+    "prepublishOnly": "bun run check",
+    "evals": "bun run evals/cli.ts"
+  },
+  "peerDependencies": {
+    "ai": "^7.0.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "ai": "^7.0.91",
+    "prettier": "^3.6.0",
+    "typescript": "^5.9.0",
+    "zod": "^4.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}