Add @theseus.run/core package with Tool primitive

First public release of theseus-core. Ships the Tool module only:
- Tool<I,O> — typed, all-Effect pipeline (decode → execute → retry → validate → encode)
- defineTool / defineToolEffect — ergonomic and full-Effect authoring APIs
- SchemaAdapter with fromZod and fromEffectSchema adapters
- callTool execution pipeline with automatic retry on retriable errors
- ToolSafety levels (readonly/write/destructive) and capability helpers
- 4 tagged error types for structured error handling

65 tests, full typecheck, CI coverage.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: romanonthego

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        package: [jsx-md, jsx-md-beautiful-mermaid]
+        package: [theseus-core, jsx-md, jsx-md-beautiful-mermaid]
     steps:
       - uses: actions/checkout@v6.0.2
       - uses: oven-sh/setup-bun@v2.2.0

bun.lock

@@ -0,0 +1,77 @@
+{
+  "name": "@theseus.run/core",
+  "version": "0.1.0",
+  "description": "Typed primitives for LLM agent systems. Start with Tool — the boundary between AI reasoning and the world.",
+  "type": "module",
+  "author": "Roman Dubinin <romanonthego@gmail.com> (https://romanonthego.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theseus-run/theseus.git",
+    "directory": "packages/theseus-core"
+  },
+  "bugs": {
+    "url": "https://github.com/theseus-run/theseus/issues"
+  },
+  "homepage": "https://theseus.run",
+  "keywords": [
+    "llm",
+    "tools",
+    "agents",
+    "effect",
+    "zod",
+    "schema",
+    "ai",
+    "function-calling",
+    "tool-use"
+  ],
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build --target=node --sourcemap=linked --splitting --external=effect --external=zod --outdir=dist src/tool/index.ts src/tool/run.ts src/tool/zod.ts src/tool/effect-schema.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "src/tool",
+    "dist"
+  ],
+  "sideEffects": false,
+  "types": "./src/tool/index.ts",
+  "exports": {
+    "./Tool": {
+      "bun": "./src/tool/index.ts",
+      "types": "./src/tool/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./Tool/run": {
+      "bun": "./src/tool/run.ts",
+      "types": "./src/tool/run.ts",
+      "import": "./dist/run.js"
+    },
+    "./Tool/zod": {
+      "bun": "./src/tool/zod.ts",
+      "types": "./src/tool/zod.ts",
+      "import": "./dist/zod.js"
+    },
+    "./Tool/effect-schema": {
+      "bun": "./src/tool/effect-schema.ts",
+      "types": "./src/tool/effect-schema.ts",
+      "import": "./dist/effect-schema.js"
+    }
+  },
+  "dependencies": {
+    "effect": "4.0.0-beta.33",
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "bun-types": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}

packages/theseus-core/package.json

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { Effect, Schema } from "effect";
+import { fromEffectSchema } from "./effect-schema.ts";
+import { defineTool } from "./index.ts";
+
+describe("fromEffectSchema", () => {
+  test("generates JSON schema from Effect Schema struct", () => {
+    const adapter = fromEffectSchema(Schema.Struct({ path: Schema.String }));
+    expect(adapter.json).toHaveProperty("type", "object");
+    expect(adapter.json).toHaveProperty("properties");
+    const props = adapter.json["properties"] as Record<string, unknown>;
+    expect(props).toHaveProperty("path");
+  });
+
+  test("decode parses valid input", () => {
+    const adapter = fromEffectSchema(Schema.Struct({ a: Schema.Number, b: Schema.Number }));
+    const result = adapter.decode({ a: 1, b: 2 });
+    expect(result).toEqual({ a: 1, b: 2 });
+  });
+
+  test("decode throws on invalid input", () => {
+    const adapter = fromEffectSchema(Schema.Struct({ path: Schema.String }));
+    expect(() => adapter.decode({ path: 123 })).toThrow();
+  });
+
+  test("works end-to-end with defineTool", async () => {
+    const tool = defineTool({
+      name: "greet",
+      description: "Greet someone",
+      inputSchema: fromEffectSchema(Schema.Struct({ name: Schema.String })),
+      safety: "readonly",
+      capabilities: [],
+      execute: ({ name }, _ctx) => Effect.succeed(`hello ${name}`),
+      encode: (s) => s,
+    });
+
+    expect(tool.name).toBe("greet");
+    expect(tool.inputSchema).toHaveProperty("type", "object");
+    const decoded = await Effect.runPromise(tool.decode({ name: "world" }));
+    expect(decoded.name).toBe("world");
+    const output = await Effect.runPromise(tool.execute(decoded));
+    const encoded = await Effect.runPromise(tool.encode(output));
+    expect(encoded).toBe("hello world");
+  });
+
+  test("handles optional fields", () => {
+    const adapter = fromEffectSchema(
+      Schema.Struct({
+        required: Schema.String,
+        optional: Schema.optional(Schema.String),
+      }),
+    );
+    const props = adapter.json["properties"] as Record<string, unknown>;
+    expect(props).toHaveProperty("required");
+
+    expect(adapter.decode({ required: "yes" })).toHaveProperty("required", "yes");
+    const both = adapter.decode({ required: "yes", optional: "also" });
+    expect(both).toHaveProperty("required", "yes");
+    expect(both).toHaveProperty("optional", "also");
+  });
+
+  test("includes required array in json", () => {
+    const adapter = fromEffectSchema(Schema.Struct({ name: Schema.String, age: Schema.Number }));
+    expect(adapter.json).toHaveProperty("required");
+    const req = adapter.json["required"] as string[];
+    expect(req).toContain("name");
+    expect(req).toContain("age");
+  });
+});

packages/theseus-core/src/tool/effect-schema.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Effect Schema adapter for Tool — converts an Effect Schema into
+ * a SchemaAdapter for use with defineTool.
+ *
+ *   const tool = defineTool({
+ *     name: "readFile",
+ *     description: "Read a file",
+ *     inputSchema: fromEffectSchema(Schema.Struct({ path: Schema.String })),
+ *     safety: "readonly",
+ *     capabilities: ["fs.read"],
+ *     execute: ({ path }, { fail }) =>
+ *       Effect.tryPromise(() => Bun.file(path).text()).pipe(
+ *         Effect.mapError((e) => fail(`Cannot read: ${path}`, e)),
+ *       ),
+ *     serialize: (s) => s,
+ *   })
+ */
+import { Schema } from "effect";
+import type { SchemaAdapter } from "./index.ts";
+
+/** Convert an Effect Schema into a SchemaAdapter for defineTool. */
+export const fromEffectSchema = <I>(schema: Schema.Schema<I>): SchemaAdapter<I> => {
+  // biome-ignore lint/suspicious/noExplicitAny: Effect v4 toJsonSchemaDocument needs Top constraint
+  const doc = Schema.toJsonSchemaDocument(schema as any);
+  const root = doc.schema as Record<string, unknown>;
+  const defs = doc.definitions;
+
+  // Inline $ref if definitions exist — most LLM APIs don't resolve $ref
+  let properties = (root["properties"] as Record<string, unknown>) ?? {};
+  const required = (root["required"] as ReadonlyArray<string>) ?? [];
+
+  if (defs && Object.keys(defs).length > 0) {
+    properties = inlineRefs(properties, defs);
+  }
+
+  return {
+    json: { type: "object", properties, required },
+    // biome-ignore lint/suspicious/noExplicitAny: Effect v4 decodeUnknownSync needs Top constraint
+    decode: (raw: unknown) => Schema.decodeUnknownSync(schema as any)(raw) as I,
+  };
+};
+
+/** Replace $ref pointers with inline definitions. */
+const inlineRefs = (
+  properties: Record<string, unknown>,
+  definitions: Record<string, unknown>,
+): Record<string, unknown> =>
+  Object.fromEntries(
+    Object.entries(properties).map(([key, value]) => [
+      key,
+      value && typeof value === "object" && "$ref" in value
+        ? definitions[(value as { $ref: string }).$ref.replace("#/$defs/", "")] ?? value
+        : value,
+    ]),
+  );