@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/surface/tools.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+/**
+ * The handler for a function tool the client answers: it returns what the client sent back for
+ * the call, which the relay bridge hands over as `ctx.host.clientOutput`. With no output the call
+ * fails to the model, naming the tool; so does a call the bridge settled because the client never
+ * answered (`host.clientTimedOut`).
+ */
+export function clientAnsweredHandler(name) {
+    return (_input, ctx) => {
+        const host = ctx.host;
+        if (host && 'clientOutput' in host)
+            return host.clientOutput;
+        if (host?.clientTimedOut) {
+            throw new Error("The page didn't answer. Look before trying again.");
+        }
+        throw new Error(`${name} runs in the client, and the client sent no result.`);
+    };
+}
+const answer = z.record(z.string(), z.unknown());
+const lookInput = z.object({
+    at: z
+        .string()
+        .optional()
+        .describe('A surface ("playground") or a node in one ("playground/identity"); leave out to see every surface'),
+});
+const actInput = z.object({
+    at: z.string().describe('The node to act on, as look names it'),
+    action: z.string().describe('One of the actions look lists for that node'),
+    input: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("The action's input, per its schema"),
+    basedOn: z
+        .number()
+        .int()
+        .optional()
+        .describe('For a write: the revision from your last look. If the page changed since, nothing applies.'),
+    intent: z
+        .string()
+        .optional()
+        .describe('A short key for what the person asked ("image-agent"), so a repeat of a starting-over action applies once'),
+});
+/** `look` and `act`: the two tools an agent uses to see and work in every surface a client mounts. */
+export function surfaceTools(options = {}) {
+    const base = {
+        type: 'function',
+        category: options.category ?? 'surface',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        output: answer,
+    };
+    return [
+        {
+            ...base,
+            name: 'look',
+            description: "See what is on the person's screen. With no `at`: every surface, its revision, summary, nodes and issue counts. With `at`: that node's fields (secrets only as cards: set, what it looks like, problems), what each means, its issues, its actions with their input schemas, and its children.",
+            access: 'read-only',
+            input: lookInput,
+            handler: clientAnsweredHandler('look'),
+        },
+        {
+            ...base,
+            name: 'act',
+            description: "Do one of a node's actions: `set` fields, `point` the person at something, or the node's own (test, send, launch…). Comes back applied, unchanged, done, stale (the page changed: look again), refused or failed, with what was rejected and why.",
+            access: 'read-write',
+            input: actInput,
+            handler: clientAnsweredHandler('act'),
+        },
+    ];
+}
+/** How to use `look` and `act`, for an agent's instructions. */
+export const SURFACE_PROMPT = `You see and work in the person's screen through surfaces, with two tools.
+- look: no \`at\` lists every surface. Look at a node before you act on it.
+- act: do one of the actions look lists. Pass basedOn (the revision from your last look) for writes.
+- Say a change is done only when act comes back applied. If it lists rejected fields, say which and why.
+- stale means the person changed something: look again, then go on. After refused or failed, look before retrying; never retry blind.
+- Secrets (keys, tokens, passwords) show only as cards: set or not, what they look like, their problems. You never see or type the value. To have the person enter one, act point on it and ask them to paste it. To find out whether it works, use the node's test action.
+- When something isn't working, look for issues, test what can be tested, and tell the person what you found in plain words.
+- A line starting "(state)" is a silent note about what changed on the page. It is background; never read it out. If it says something you did applied late or was cancelled, tell the person once, in a few words.`;

package/esm/src/surface/types.d.ts

@@ -0,0 +1,104 @@
+import type { z } from 'zod';
+/**
+ * How a field's value leaves the page. The runtime projects every value through
+ * its format before an agent sees it, so a page cannot forget to.
+ * - `secret`: only a card (set, what it looks like, what is wrong with it), never the value.
+ * - `url`: credential query parameters and `user:pass@` masked.
+ * - `headers`: a JSON object of headers, credential-named values masked.
+ * - `text` (the default): as is, then scrubbed with every other answer.
+ */
+export type SurfaceFieldFormat = 'secret' | 'url' | 'headers' | 'text';
+export interface SurfaceField {
+    value: unknown;
+    /** The kind of value, as the agent should read it ("boolean", "one of …"). */
+    type?: string;
+    /** What the setting means. */
+    doc?: string;
+    options?: readonly unknown[];
+    format?: SurfaceFieldFormat;
+    /** Why the agent may not `set` it; the person still can. */
+    readOnly?: string;
+    /** For a secret: what uses it, so its card can say. */
+    usedBy?: readonly string[];
+}
+/** Something wrong on a node, or on one of its fields. */
+export interface SurfaceIssue {
+    node: string;
+    field?: string;
+    message: string;
+}
+/** A change that was not made, and why. */
+export interface SurfaceRejection {
+    field: string;
+    why: string;
+}
+/**
+ * - `read`: changes nothing.
+ * - `run`: does something outside the surface (tests a key, sends a message, exports).
+ * - `write`: changes the surface; it needs the revision the agent last saw.
+ */
+export type SurfaceEffect = 'read' | 'run' | 'write';
+/** Who a change is by, for the surface to record: notes are told only about the person's. */
+export type SurfaceAuthor = 'person' | 'agent';
+export interface SurfaceActionContext {
+    callId: string;
+    by: SurfaceAuthor;
+}
+export interface SurfaceActionOutcome {
+    rejected?: SurfaceRejection[];
+    /** What the action found or made; scrubbed like everything else. */
+    result?: unknown;
+    /** The node the change landed on (local id), shown back to the agent. */
+    node?: string;
+}
+export interface SurfaceAction<Input = Record<string, unknown>> {
+    description: string;
+    effect: SurfaceEffect;
+    /** Checked before `run`; each issue comes back as a rejection. */
+    input?: z.ZodType<Input>;
+    /** A write that starts something over: the same `intent` again within a minute replays. */
+    intent?: boolean;
+    run(input: Input, ctx: SurfaceActionContext): SurfaceActionOutcome | Promise<SurfaceActionOutcome>;
+}
+export interface SurfaceNode {
+    /** Unique in its surface. The root's is `''`, addressed by the surface id alone. */
+    id: string;
+    title: string;
+    /** The parent's id; the root has none. */
+    parent?: string;
+    summary?: string;
+    fields?(): Record<string, SurfaceField>;
+    /**
+     * Applies field changes the runtime has checked: each names a field (or a dotted path in one),
+     * and none is a secret or read-only.
+     */
+    set?(changes: Record<string, unknown>, ctx: SurfaceActionContext): {
+        rejected: SurfaceRejection[];
+    };
+    /** Shows the node, or one of its fields, to the person: selects it, scrolls to it, focuses it. */
+    point?(field?: string): void;
+    actions?: Record<string, SurfaceAction<never>>;
+}
+export interface SurfaceChange {
+    revision: number;
+    by: SurfaceAuthor;
+    /** Local ids of the nodes it touched. */
+    nodes: readonly string[];
+}
+/** What a page mounts so an agent can see it and work in it. */
+export interface Surface {
+    id: string;
+    title: string;
+    revision(): number;
+    /** One line: what is here and where it stands. */
+    summary(): string;
+    /** Read fresh on every call. The first is the root. */
+    nodes(): readonly SurfaceNode[];
+    issues?(): readonly SurfaceIssue[];
+    changesSince?(revision: number): readonly SurfaceChange[];
+    subscribe?(listener: () => void): () => void;
+    /** Secret values by name, so any answer that carries one is scrubbed. Read per answer, never kept. */
+    secrets?(): Record<string, string>;
+}
+/** Defines an action with its input type inferred, then erased for `SurfaceNode.actions`. */
+export declare function defineAction<Input>(action: SurfaceAction<Input>): SurfaceAction<never>;

package/esm/src/surface/types.js

@@ -0,0 +1,4 @@
+/** Defines an action with its input type inferred, then erased for `SurfaceNode.actions`. */
+export function defineAction(action) {
+    return action;
+}

package/package.json

@@ -1,6 +1,110 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
+  "keywords": [
+    "agent",
+    "ai",
+    "kernel",
+    "llm",
+    "typescript",
+    "deno",
+    "node",
+    "openrouter",
+    "gemini"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/masudl-hub/theoremai"
+  },
+  "license": "MIT",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js"
+    },
+    "./kernel": {
+      "import": "./esm/src/kernel/mod.js"
+    },
+    "./providers": {
+      "import": "./esm/src/providers/mod.js"
+    },
+    "./providers/local": {
+      "import": "./esm/src/providers/local/mod.js"
+    },
+    "./guardrails": {
+      "import": "./esm/src/guardrails/mod.js"
+    },
+    "./guardrails/testing": {
+      "import": "./esm/src/guardrails/testing.js"
+    },
+    "./guardrails/compile": {
+      "import": "./esm/src/guardrails/compile-egress.js"
+    },
+    "./observability": {
+      "import": "./esm/src/observability/mod.js"
+    },
+    "./observability/jsonl": {
+      "import": "./esm/src/observability/jsonl.js"
+    },
+    "./observability/openinference": {
+      "import": "./esm/src/observability/openinference.js"
+    },
+    "./observability/phoenix": {
+      "import": "./esm/src/observability/phoenix.js"
+    },
+    "./host": {
+      "import": "./esm/src/host/mod.js"
+    },
+    "./interface": {
+      "import": "./esm/src/interface/mod.js"
+    },
+    "./surface": {
+      "import": "./esm/src/surface/mod.js"
+    },
+    "./cli": {
+      "import": "./esm/src/cli/index.js"
+    },
+    "./presets": {
+      "import": "./esm/src/presets/mod.js"
+    },
+    "./presets/google": {
+      "import": "./esm/src/presets/google.js"
+    },
+    "./presets/google/speech-voices": {
+      "import": "./esm/src/presets/google/speech-voices.js"
+    },
+    "./schema": {
+      "import": "./esm/src/kernel/schema.js"
+    },
+    "./evals": {
+      "import": "./esm/src/evals/mod.js"
+    },
+    "./providers/google/live": {
+      "import": "./esm/src/providers/google/live/mod.js"
+    }
+  },
+  "scripts": {},
+  "bin": {
+    "agents": "esm/src/cli/bin.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "dependencies": {
+    "@eslint-community/regexpp": "4.12.2",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
+    "ai": "^7.0.0",
+    "gpt-tokenizer": "^4.0.0",
+    "refa": "0.12.1"
+  },
+  "peerDependencies": {
+    "zod": "^4.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43"
+  },
+  "_generatedBy": "dnt@0.43.2"
+}