@a-dray/aglib 0.1.0

package/dist/tools/tool.d.ts

@@ -0,0 +1,106 @@
+import type { Content } from "../content.js";
+import type { Delivery, ToolCall, ToolResult } from "../session/entry.js";
+import type { JsonValue } from "../json.js";
+import { type Result } from "../result.js";
+import { z } from "zod";
+/** What a tool tells a model about itself. Declared here because a tool owns it. */
+export interface ToolSpec {
+    name: string;
+    description: string;
+    /** JSON Schema. */
+    parameters: JsonValue;
+    annotations?: {
+        readOnly?: boolean;
+        sequential?: boolean;
+    };
+}
+export interface ToolContext {
+    sessionId: string;
+    runId: string;
+    callId: string;
+    signal: AbortSignal;
+    /**
+     * Deliver input to another session, committed with this run's own entries.
+     * This is the whole of agent-to-agent messaging: spawning a child, replying
+     * to a parent and messaging a peer are the same call, and either the sending
+     * turn commits with the delivery or neither happens.
+     */
+    enqueue(delivery: Delivery): void;
+    /** Progress for a live viewer. Never recovery state. */
+    report(data: JsonValue): void;
+}
+export interface Tool {
+    spec: ToolSpec;
+    /** Validates raw arguments once, before any authority decision sees them. */
+    prepare(raw: unknown): Result<{
+        input: JsonValue;
+        run(context: ToolContext): Promise<ToolResult>;
+    }, ToolResult>;
+}
+/**
+ * The entire permission model.
+ *
+ * One function over parsed arguments, supplied by the application, which
+ * already owns identity, tenancy and policy. There is no grant vocabulary, no
+ * principal and no second batch-level hook: anything those expressed, a closure
+ * expresses better.
+ *
+ * Two outcomes, not three. There was a `pause`, which parked the batch and
+ * committed an approval request — and nothing could ever resolve it, because
+ * resuming an exact batch is only possible in a harness we own, and three of
+ * the four are not. An approval that works in one harness and dead-ends in the
+ * others is worse than none. A call needing permission is rejected with a
+ * message saying so; the application asks whoever approves, and their answer
+ * arrives as ordinary input on the session, which is a path that already works
+ * everywhere. `recipes/agent-service` shows the whole round trip.
+ *
+ * The gate does not weaken by being a rejection: this runs on every call and
+ * cannot be routed around. What an application gives up is exact-argument
+ * replay, since the model re-issues rather than resuming. An application that
+ * needs the stronger thing keys its approval on the call id and a hash of the
+ * parsed input, so a re-issue that differs misses and is refused again.
+ */
+export type Decide = (call: {
+    tool: ToolSpec;
+    input: JsonValue;
+    sessionId: string;
+    runId: string;
+    callId: string;
+}) => {
+    action: "execute";
+} | {
+    action: "reject";
+    message: string;
+} | Promise<{
+    action: "execute";
+} | {
+    action: "reject";
+    message: string;
+}>;
+/** What a harness is handed to reach application tools. */
+export interface ToolExecutor {
+    list(): readonly ToolSpec[];
+    execute(input: {
+        calls: readonly ToolCall[];
+        signal?: AbortSignal;
+    }): Promise<{
+        results: readonly {
+            callId: string;
+            result: ToolResult;
+        }[];
+    }>;
+}
+/**
+ * Declares a tool from a runtime schema. The argument type of `execute` is
+ * derived from that schema, so there is never a hand-maintained interface to
+ * keep in step with the validation.
+ */
+export declare function defineTool<TSchema extends z.ZodType>(input: {
+    name: string;
+    description: string;
+    schema: TSchema;
+    annotations?: ToolSpec["annotations"];
+    execute(args: z.output<TSchema>, context: ToolContext): ToolResult | Promise<ToolResult>;
+}): Tool;
+/** Re-exported for the same reason the model port re-exports its own. */
+export type { Content, ToolResult };

package/dist/tools/tool.js

@@ -0,0 +1,34 @@
+import { err, ok } from "../result.js";
+import { z } from "zod";
+/**
+ * Declares a tool from a runtime schema. The argument type of `execute` is
+ * derived from that schema, so there is never a hand-maintained interface to
+ * keep in step with the validation.
+ */
+export function defineTool(input) {
+    const parameters = z.toJSONSchema(input.schema);
+    return Object.freeze({
+        spec: Object.freeze({
+            name: input.name,
+            description: input.description,
+            parameters,
+            ...(input.annotations ? { annotations: input.annotations } : {}),
+        }),
+        prepare(raw) {
+            const parsed = input.schema.safeParse(raw);
+            if (!parsed.success) {
+                return err({
+                    content: `Invalid arguments for ${input.name}: ${z.prettifyError(parsed.error)}`,
+                    isError: true,
+                });
+            }
+            return ok({
+                input: parsed.data,
+                // Throws are normalized by the executor, which has to cover
+                // hand-written tools anyway; catching here too would be dead code.
+                run: async (context) => input.execute(parsed.data, context),
+            });
+        },
+    });
+}
+//# sourceMappingURL=tool.js.map

package/dist/tools/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/tools/tool.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,GAAG,EAAE,EAAE,EAAe,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0ExB;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAA4B,KAMrD;IACC,MAAM,UAAU,GAAG,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAc,CAAC;IAC7D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC;YAClB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,UAAU;YACV,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC;QACF,OAAO,CAAC,GAAY;YAClB,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;YAC3C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,OAAO,GAAG,CAAC;oBACT,OAAO,EAAE,yBAAyB,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;oBAChF,OAAO,EAAE,IAAI;iBACd,CAAC,CAAC;YACL,CAAC;YACD,OAAO,EAAE,CAAC;gBACR,KAAK,EAAE,MAAM,CAAC,IAAiB;gBAC/B,4DAA4D;gBAC5D,mEAAmE;gBACnE,GAAG,EAAE,KAAK,EAAE,OAAoB,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAyB,EAAE,OAAO,CAAC;aAC9F,CAAC,CAAC;QACL,CAAC;KACF,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { Content } from \"../content.js\";\n\nimport type { Delivery, ToolCall, ToolResult } from \"../session/entry.js\";\nimport type { JsonValue } from \"../json.js\";\nimport { err, ok, type Result } from \"../result.js\";\nimport { z } from \"zod\";\n\n/** What a tool tells a model about itself. Declared here because a tool owns it. */\nexport interface ToolSpec {\n  name: string;\n  description: string;\n  /** JSON Schema. */\n  parameters: JsonValue;\n  annotations?: { readOnly?: boolean; sequential?: boolean };\n}\n\nexport interface ToolContext {\n  sessionId: string;\n  runId: string;\n  callId: string;\n  signal: AbortSignal;\n  /**\n   * Deliver input to another session, committed with this run's own entries.\n   * This is the whole of agent-to-agent messaging: spawning a child, replying\n   * to a parent and messaging a peer are the same call, and either the sending\n   * turn commits with the delivery or neither happens.\n   */\n  enqueue(delivery: Delivery): void;\n  /** Progress for a live viewer. Never recovery state. */\n  report(data: JsonValue): void;\n}\n\nexport interface Tool {\n  spec: ToolSpec;\n  /** Validates raw arguments once, before any authority decision sees them. */\n  prepare(raw: unknown): Result<{ input: JsonValue; run(context: ToolContext): Promise<ToolResult> }, ToolResult>;\n}\n\n/**\n * The entire permission model.\n *\n * One function over parsed arguments, supplied by the application, which\n * already owns identity, tenancy and policy. There is no grant vocabulary, no\n * principal and no second batch-level hook: anything those expressed, a closure\n * expresses better.\n *\n * Two outcomes, not three. There was a `pause`, which parked the batch and\n * committed an approval request — and nothing could ever resolve it, because\n * resuming an exact batch is only possible in a harness we own, and three of\n * the four are not. An approval that works in one harness and dead-ends in the\n * others is worse than none. A call needing permission is rejected with a\n * message saying so; the application asks whoever approves, and their answer\n * arrives as ordinary input on the session, which is a path that already works\n * everywhere. `recipes/agent-service` shows the whole round trip.\n *\n * The gate does not weaken by being a rejection: this runs on every call and\n * cannot be routed around. What an application gives up is exact-argument\n * replay, since the model re-issues rather than resuming. An application that\n * needs the stronger thing keys its approval on the call id and a hash of the\n * parsed input, so a re-issue that differs misses and is refused again.\n */\nexport type Decide = (call: {\n  tool: ToolSpec;\n  input: JsonValue;\n  sessionId: string;\n  runId: string;\n  callId: string;\n}) =>\n  | { action: \"execute\" }\n  | { action: \"reject\"; message: string }\n  | Promise<{ action: \"execute\" } | { action: \"reject\"; message: string }>;\n\n/** What a harness is handed to reach application tools. */\nexport interface ToolExecutor {\n  list(): readonly ToolSpec[];\n  execute(input: { calls: readonly ToolCall[]; signal?: AbortSignal }):\n    Promise<{ results: readonly { callId: string; result: ToolResult }[] }>;\n}\n\n/**\n * Declares a tool from a runtime schema. The argument type of `execute` is\n * derived from that schema, so there is never a hand-maintained interface to\n * keep in step with the validation.\n */\nexport function defineTool<TSchema extends z.ZodType>(input: {\n  name: string;\n  description: string;\n  schema: TSchema;\n  annotations?: ToolSpec[\"annotations\"];\n  execute(args: z.output<TSchema>, context: ToolContext): ToolResult | Promise<ToolResult>;\n}): Tool {\n  const parameters = z.toJSONSchema(input.schema) as JsonValue;\n  return Object.freeze({\n    spec: Object.freeze({\n      name: input.name,\n      description: input.description,\n      parameters,\n      ...(input.annotations ? { annotations: input.annotations } : {}),\n    }),\n    prepare(raw: unknown) {\n      const parsed = input.schema.safeParse(raw);\n      if (!parsed.success) {\n        return err({\n          content: `Invalid arguments for ${input.name}: ${z.prettifyError(parsed.error)}`,\n          isError: true,\n        });\n      }\n      return ok({\n        input: parsed.data as JsonValue,\n        // Throws are normalized by the executor, which has to cover\n        // hand-written tools anyway; catching here too would be dead code.\n        run: async (context: ToolContext) => input.execute(parsed.data as z.output<TSchema>, context),\n      });\n    },\n  });\n}\n\n/** Re-exported for the same reason the model port re-exports its own. */\nexport type { Content, ToolResult };\n"]}

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@a-dray/aglib",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A small TypeScript toolkit for building your own agent harness.",
+  "license": "MIT",
+  "author": "Adam Dray",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aj-dray/aglib.git"
+  },
+  "packageManager": "bun@1.3.14",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./session": {
+      "types": "./dist/session/index.d.ts",
+      "import": "./dist/session/index.js"
+    },
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "import": "./dist/tools/index.js"
+    },
+    "./model": {
+      "types": "./dist/model/index.d.ts",
+      "import": "./dist/model/index.js"
+    },
+    "./model/conformance": {
+      "types": "./dist/model/conformance.d.ts",
+      "import": "./dist/model/conformance.js"
+    },
+    "./model/adapters/anthropic": {
+      "types": "./dist/model/adapters/anthropic/index.d.ts",
+      "import": "./dist/model/adapters/anthropic/index.js"
+    },
+    "./model/adapters/openai-compatible": {
+      "types": "./dist/model/adapters/openai-compatible/index.d.ts",
+      "import": "./dist/model/adapters/openai-compatible/index.js"
+    },
+    "./model/adapters/fake": {
+      "types": "./dist/model/adapters/fake/index.d.ts",
+      "import": "./dist/model/adapters/fake/index.js"
+    },
+    "./store": {
+      "types": "./dist/store/index.d.ts",
+      "import": "./dist/store/index.js"
+    },
+    "./store/conformance": {
+      "types": "./dist/store/conformance.d.ts",
+      "import": "./dist/store/conformance.js"
+    },
+    "./store/adapters/sqlite": {
+      "types": "./dist/store/adapters/sqlite.d.ts",
+      "import": "./dist/store/adapters/sqlite.js"
+    },
+    "./harness": {
+      "types": "./dist/harness/index.d.ts",
+      "import": "./dist/harness/index.js"
+    },
+    "./harness/adapters/acp": {
+      "types": "./dist/harness/adapters/acp/index.d.ts",
+      "import": "./dist/harness/adapters/acp/index.js"
+    },
+    "./sandbox": {
+      "types": "./dist/sandbox/index.d.ts",
+      "import": "./dist/sandbox/index.js"
+    },
+    "./sandbox/conformance": {
+      "types": "./dist/sandbox/conformance.d.ts",
+      "import": "./dist/sandbox/conformance.js"
+    },
+    "./sandbox/adapters/local": {
+      "types": "./dist/sandbox/adapters/local.d.ts",
+      "import": "./dist/sandbox/adapters/local.js"
+    },
+    "./sandbox/adapters/docker": {
+      "types": "./dist/sandbox/adapters/docker.d.ts",
+      "import": "./dist/sandbox/adapters/docker.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^6.0.3"
+  },
+  "workspaces": [
+    "recipes/*"
+  ],
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "prepare": "bun run build",
+    "check": "bun run typecheck && bun test src scripts && bun run build && bun run node:verify && bun run recipes:verify && bun run docs:check && bun scripts/checks.ts",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.scripts.json",
+    "test": "bun run build && bun test src scripts recipes",
+    "checks": "bun run build && bun scripts/checks.ts",
+    "recipes:verify": "tsc -p tsconfig.recipes.json && bun test recipes",
+    "recipe": "bun run build && bun scripts/recipe.ts",
+    "docs": "bun scripts/docs.ts",
+    "docs:check": "bun scripts/docs.ts --check",
+    "node:verify": "node scripts/node-verify.mjs",
+    "prepack": "bun run build"
+  }
+}