@intx/agent 0.1.2 → 0.3.0

package/dist/tool.js

@@ -0,0 +1,244 @@
+// Tool registration and dispatch.
+//
+// Two registration shapes are supported for per-tool authoring:
+//
+//   `tool({ definition, handler })`        - handler receives the full
+//                                            ToolCall and returns the full
+//                                            ToolResult. Use when the
+//                                            handler needs the callId or
+//                                            wants to set isError/detail/
+//                                            pendingMarker.
+//
+//   `stringTool({ definition, handler })`  - sugar for the common case of
+//                                            "compute a string from the
+//                                            parsed arguments." The callId
+//                                            is filled in from the
+//                                            surrounding ToolCall, and
+//                                            isError is false unless the
+//                                            handler throws.
+//
+// `createToolRunner(tools)` builds a `ToolRunner` that dispatches by tool
+// name. Per the ToolRunner contract (packages/types/src/runtime.ts), `run`
+// must not throw -- unknown tool names and handler exceptions are surfaced
+// as `ToolResult` with `isError: true` so the model sees them and can
+// recover.
+//
+// `defineTool({ id, requires?, factory })` is the env-DI factory shape.
+// It produces an
+// `AnnotatedToolFactory` whose `factory(env)` returns a `ToolBundle`
+// exposing a set of tool definitions, a dispatcher, and an optional
+// disposer. Bundle-style (rather than per-tool) factory shapes match
+// the existing posix-tools and mail-tools ergonomics; a package that
+// wants per-tool granularity wraps each tool in its own single-
+// definition bundle.
+import { validateNamespacedId } from "./namespace.js";
+export function tool(args) {
+    return { kind: "full", definition: args.definition, handler: args.handler };
+}
+export function stringTool(args) {
+    return {
+        kind: "string",
+        definition: args.definition,
+        handler: args.handler,
+    };
+}
+/**
+ * Adapt a pre-built ToolRunner (e.g. the one returned by
+ * `createPosixTools`) into a list of AgentTools that can be passed to
+ * `createAgent({ tools })`. Each definition becomes a full-handler
+ * AgentTool that delegates to the runner's `run`.
+ *
+ * Use this when integrating tool packages whose public surface is a
+ * single ToolRunner rather than individual handlers.
+ */
+export function fromToolRunner(runner) {
+    return runner.definitions.map((definition) => ({
+        kind: "full",
+        definition,
+        handler: (call, signal) => runner.run(call, signal),
+    }));
+}
+export class DuplicateToolError extends Error {
+    toolName;
+    constructor(toolName) {
+        super(`duplicate tool name: ${toolName}`);
+        this.name = "DuplicateToolError";
+        this.toolName = toolName;
+    }
+}
+/**
+ * Map a tool's static approval mark to the `GrantEffect` floor its
+ * `tool:<name>` grant carries: an `ask`-marked tool floors at `ask` (its
+ * invocation must clear an approval gate), every other tool floors at
+ * `allow`.
+ *
+ * This is the single canonical derivation of a tool's authorization floor
+ * from its declaration. Both the deploy-time capability walk (hub-side)
+ * and the per-step tool authorization (sidecar-side) route through here so
+ * a pinned tool loaded in the child derives the SAME floor the walk would
+ * have derived from an inline declaration. A divergence between the two
+ * sites would let a pinned `ask` tool authorize as `allow` (or vice
+ * versa), so the mapping lives in exactly one place.
+ */
+export function toolApprovalEffect(declaration) {
+    return declaration.approval === "ask" ? "ask" : "allow";
+}
+/**
+ * Define a tool bundle factory.
+ *
+ *   - `id` must be package-namespaced ("@vendor/pkg/name" or
+ *     "pkg/name"). Bare ids throw `Error` at definition time.
+ *   - `requires` enumerates the env keys this factory touches beyond
+ *     `BaseEnv`'s six core fields. The runtime `validateEnv` checks
+ *     presence; the factory itself may also fail loud at construction
+ *     if the env contents are structurally wrong.
+ *   - `definitions` statically declares the tool names this factory
+ *     contributes so callers (e.g. the deploy-time capability walk) can
+ *     enumerate them without instantiating the factory.
+ *   - `factory(env)` returns a `ToolBundle`. Invoked once per agent
+ *     instantiation; the bundle's lifetime is tied to that agent.
+ *
+ * The returned object is the same callable as the supplied `factory`
+ * with `id`, a frozen `requires` array, and a frozen `definitions`
+ * array attached.
+ */
+export function defineTool(opts) {
+    validateNamespacedId(opts.id);
+    const requires = Object.freeze([
+        ...(opts.requires ?? []),
+    ]);
+    const definitions = Object.freeze([
+        ...opts.definitions,
+    ]);
+    // Wrap the caller's factory rather than mutating it. A caller that
+    // shares a factory function across multiple `defineTool` calls
+    // (e.g. registering the same constructor under two ids in different
+    // bundles) needs each `AnnotatedToolFactory` to be a distinct
+    // identity with its own metadata; a direct `Object.assign` on
+    // `opts.factory` would let the second call silently overwrite the
+    // first's annotations.
+    const wrapped = (env) => opts.factory(env);
+    return Object.assign(wrapped, {
+        id: opts.id,
+        requires,
+        definitions,
+    });
+}
+/**
+ * Registered symbol that tags `AnnotatedPluginFactory` values. Exported
+ * so consumers that need to introspect plugin factories directly can
+ * read the marker without re-registering the key.
+ */
+export const PLUGIN_MARKER = Symbol.for("@intx/agent.plugin");
+/**
+ * Constant on every plugin instance returned by `definePlugin`. Hosts
+ * that need to distinguish plugin instances from arbitrary objects
+ * received via `env.plugins` check this field before duck-typing on
+ * shape. The string value is the operative form of the contract — the
+ * value-side marker exists because the factory-side symbol marker
+ * (PLUGIN_MARKER above) is only visible to code that imported it,
+ * while the kind string travels through pure-JSON inspection too.
+ */
+export const TOOL_PLUGIN_KIND = "tool-plugin";
+/**
+ * Predicate hosts use to confirm a value off `env.plugins` was minted
+ * by `definePlugin` rather than happening to satisfy a shape-based
+ * check. Returns true iff the value is an object carrying the
+ * literal `kind: "tool-plugin"` marker.
+ */
+export function isToolPluginInstance(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    if (!("kind" in value))
+        return false;
+    return value.kind === TOOL_PLUGIN_KIND;
+}
+/**
+ * Define a plugin factory. The plugin's `Result` is host-defined and
+ * surfaces in `env.plugins` for the host-side tool factories that
+ * consume it. The returned instance is tagged with
+ * `kind: "tool-plugin"` so hosts can identify plugin instances
+ * structurally without falling back to duck-typing on the result's
+ * own shape.
+ *
+ * `id` must be package-namespaced — same rule as `defineTool` — so
+ * audit provenance threads through plugins as cleanly as through
+ * tools.
+ */
+export function definePlugin(opts) {
+    validateNamespacedId(opts.id);
+    const requires = Object.freeze([
+        ...(opts.requires ?? []),
+    ]);
+    const definitions = Object.freeze([
+        ...(opts.definitions ?? []),
+    ]);
+    const wrapped = (env) => {
+        const instance = opts.factory(env);
+        // Re-stamping the marker is harmless if the factory chose to set
+        // it itself; otherwise we add it. Either way the returned value
+        // carries the contract.
+        return Object.assign(instance, { kind: TOOL_PLUGIN_KIND });
+    };
+    return Object.assign(wrapped, {
+        id: opts.id,
+        requires,
+        definitions,
+        [PLUGIN_MARKER]: true,
+    });
+}
+/** Type predicate distinguishing plugin factories from tool factories. */
+export function isAnnotatedPluginFactory(value) {
+    if (typeof value !== "function")
+        return false;
+    if (!(PLUGIN_MARKER in value))
+        return false;
+    // `PLUGIN_MARKER in value` narrows `value` to include the symbol
+    // key, so the index access below is type-safe without a cast.
+    return value[PLUGIN_MARKER] === true;
+}
+/**
+ * Build a `ToolRunner` that dispatches by tool name. Throws
+ * `DuplicateToolError` at construction if any two tools share a name.
+ *
+ * At call time, unknown tool names and exceptions from handlers are
+ * converted to `ToolResult { isError: true }` so the contract on
+ * `ToolRunner.run` ("must not throw") is upheld.
+ */
+export function createToolRunner(tools) {
+    const byName = new Map();
+    for (const t of tools) {
+        if (byName.has(t.definition.name)) {
+            throw new DuplicateToolError(t.definition.name);
+        }
+        byName.set(t.definition.name, t);
+    }
+    const definitions = tools.map((t) => t.definition);
+    return {
+        definitions,
+        async run(call, signal) {
+            const found = byName.get(call.name);
+            if (found === undefined) {
+                return {
+                    callId: call.id,
+                    content: `unknown tool: ${call.name}`,
+                    isError: true,
+                };
+            }
+            try {
+                if (found.kind === "full") {
+                    return await found.handler(call, signal);
+                }
+                const text = await found.handler(call.arguments, signal);
+                return { callId: call.id, content: text };
+            }
+            catch (err) {
+                return {
+                    callId: call.id,
+                    content: err instanceof Error ? err.message : String(err),
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/package.json

@@ -1,19 +1,38 @@
 {
   "name": "@intx/agent",
-  "version": "0.1.2",
+  "description": "In-process agent runtime: construct an agent, send it a message, get a reply",
+  "version": "0.3.0",
   "license": "LGPL-2.1-only",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "intx-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "intx-src": "./src/testing/index.ts",
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
     }
   },
   "dependencies": {
-    "@intx/inference": "0.0.0",
-    "@intx/mime": "0.0.0",
-    "@intx/storage-isogit": "0.0.0",
-    "@intx/types": "0.0.0",
+    "@intx/inference": "0.3.0",
+    "@intx/log": "0.3.0",
+    "@intx/mime": "0.3.0",
+    "@intx/types": "0.3.0",
     "arktype": "^2.1.29"
+  },
+  "devDependencies": {
+    "@intx/storage-isogit": "0.3.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/agent.test.ts

@@ -1,46 +0,0 @@
-import { describe, test, expect } from "bun:test";
-
-import type { ContextStore, InferenceSource } from "@intx/types/runtime";
-
-import { AgentConfigError, createAgent } from "./agent";
-
-const SOURCE: InferenceSource = {
-  id: "anthropic:claude-3-5-sonnet",
-  provider: "anthropic",
-  baseURL: "https://api.anthropic.com",
-  apiKey: "sk-test",
-  model: "claude-3-5-sonnet",
-};
-
-function stubContextStore(): ContextStore {
-  // Storage-validation tests reject before touching the store; the stub
-  // never has any of its methods called.
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- test stub, never invoked
-  return {} as ContextStore;
-}
-
-describe("createAgent storage configuration", () => {
-  test("rejects when both contextStore and contextDir are given", async () => {
-    await expect(
-      createAgent({
-        contextStore: stubContextStore(),
-        contextDir: "/tmp/agent-config-1",
-        sources: [SOURCE],
-        defaultSource: SOURCE.id,
-        systemPrompt: "test",
-        tools: [],
-      }),
-    ).rejects.toBeInstanceOf(AgentConfigError);
-  });
-
-  test("rejects when neither contextStore nor contextDir is given", async () => {
-    await expect(
-      createAgent({
-        sources: [SOURCE],
-        defaultSource: SOURCE.id,
-        systemPrompt: "test",
-        tools: [],
-      }),
-    ).rejects.toBeInstanceOf(AgentConfigError);
-  });
-});