torus-ai 0.1.0

package/src/tools.ts

@@ -0,0 +1,84 @@
+import type {
+  JSONSchema,
+  SdkMcpServer,
+  ToolContext,
+  ToolDefinition,
+  ToolResultPayload,
+  ToolSchema,
+} from "./types.ts";
+
+/**
+ * Define a custom tool. Mirrors `tool()` from the Claude Agent SDK.
+ *   tool("get_temp", "Get temperature", { type:"object", ... }, async (input, ctx) => ...)
+ */
+export function tool(
+  name: string,
+  description: string,
+  inputSchema: JSONSchema,
+  handler: (input: any, ctx: ToolContext) => Promise<ToolResultPayload> | ToolResultPayload,
+): ToolDefinition {
+  return { name, description, inputSchema, handler };
+}
+
+/**
+ * Bundle tools into an in-process MCP server. Mirrors `createSdkMcpServer()`.
+ * Tools become namespaced `mcp__<name>__<tool>` when registered.
+ */
+export function createSdkMcpServer(opts: {
+  name: string;
+  version?: string;
+  tools: ToolDefinition[];
+}): SdkMcpServer {
+  return { kind: "sdk-mcp", name: opts.name, version: opts.version ?? "1.0.0", tools: opts.tools };
+}
+
+export interface RegisteredTool {
+  fullName: string; // "mcp__research__lookup" or built-in "read_file"
+  def: ToolDefinition;
+}
+
+/** Holds the model-facing tool catalog and executes calls by namespaced name. */
+export class ToolRegistry {
+  private map = new Map<string, ToolDefinition>();
+
+  /** Built-ins register under their bare name (no namespace). */
+  addBuiltins(defs: ToolDefinition[]): this {
+    for (const d of defs) this.map.set(d.name, d);
+    return this;
+  }
+
+  /** SDK MCP server tools register as mcp__<server>__<tool>. */
+  addServer(server: SdkMcpServer): this {
+    for (const t of server.tools) this.map.set(`mcp__${server.name}__${t.name}`, t);
+    return this;
+  }
+
+  has(fullName: string): boolean {
+    return this.map.has(fullName);
+  }
+
+  list(): RegisteredTool[] {
+    return [...this.map.entries()].map(([fullName, def]) => ({ fullName, def }));
+  }
+
+  /** Tool schemas to hand the model, optionally filtered to a stage's allowlist. */
+  schemas(filter?: (fullName: string) => boolean): ToolSchema[] {
+    return this.list()
+      .filter((t) => !filter || filter(t.fullName))
+      .map((t) => ({ name: t.fullName, description: t.def.description, inputSchema: t.def.inputSchema }));
+  }
+
+  async execute(
+    fullName: string,
+    input: Record<string, unknown>,
+    ctx: ToolContext,
+  ): Promise<ToolResultPayload> {
+    const def = this.map.get(fullName);
+    if (!def) return { content: `Unknown tool: ${fullName}`, isError: true };
+    try {
+      return await def.handler(input, ctx);
+    } catch (err) {
+      return { content: `Tool ${fullName} threw: ${(err as Error).message}`, isError: true };
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,111 @@
+// ─────────────────────────────────────────────────────────────────────────
+// Core wire types — the plain-data interface every layer speaks (ICM principle 2:
+// "plain text/structured data is the interface"). No provider-specific shapes leak
+// past this file; the AnthropicProvider/MockProvider translate to and from these.
+// ─────────────────────────────────────────────────────────────────────────
+
+export type Role = "user" | "assistant";
+
+export interface TextBlock {
+  type: "text";
+  text: string;
+}
+export interface ToolUseBlock {
+  type: "tool_use";
+  id: string;
+  name: string; // namespaced name as offered to the model, e.g. "mcp__research__lookup"
+  input: Record<string, unknown>;
+}
+export interface ToolResultBlock {
+  type: "tool_result";
+  toolUseId: string;
+  content: string;
+  isError?: boolean;
+}
+export type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock;
+
+export interface Message {
+  role: Role;
+  content: ContentBlock[];
+}
+
+export type StopReason = "end_turn" | "tool_use" | "max_turns";
+
+export interface ModelResponse {
+  content: ContentBlock[];
+  stopReason: StopReason;
+}
+
+export type JSONSchema = Record<string, unknown>;
+
+export interface ToolSchema {
+  name: string;
+  description: string;
+  inputSchema: JSONSchema;
+}
+
+export interface ModelRequest {
+  system: string;
+  messages: Message[];
+  tools: ToolSchema[];
+}
+
+/** The one capability the SDK needs from any model backend. Swap freely. */
+export interface ModelProvider {
+  readonly name: string;
+  generate(req: ModelRequest): Promise<ModelResponse>;
+}
+
+// ── Tools ────────────────────────────────────────────────────────────────
+
+export interface ToolResultPayload {
+  content: string;
+  isError?: boolean;
+}
+
+export interface ToolContext {
+  workspaceDir: string;
+  stageDir?: string;
+  signal?: AbortSignal;
+}
+
+export interface ToolDefinition {
+  name: string; // bare name, e.g. "lookup"; namespacing is applied at registration
+  description: string;
+  inputSchema: JSONSchema;
+  handler: (
+    input: any,
+    ctx: ToolContext,
+  ) => Promise<ToolResultPayload> | ToolResultPayload;
+}
+
+/** An in-process MCP server: tools that run in this same process, no subprocess. */
+export interface SdkMcpServer {
+  kind: "sdk-mcp";
+  name: string; // becomes the mcp__<name>__ namespace prefix
+  version: string;
+  tools: ToolDefinition[];
+}
+
+// ── Permissions ────────────────────────────────────────────────────────────
+
+export type PermissionDecision =
+  | { behavior: "allow"; updatedInput?: Record<string, unknown> }
+  | { behavior: "deny"; message: string };
+
+export type CanUseTool = (
+  toolName: string,
+  input: Record<string, unknown>,
+) => Promise<PermissionDecision> | PermissionDecision;
+
+// ── Streaming events ───────────────────────────────────────────────────────
+
+export type AgentEvent =
+  | { type: "assistant_text"; text: string; stage?: string }
+  | { type: "tool_use"; name: string; input: Record<string, unknown>; stage?: string }
+  | { type: "tool_result"; name: string; content: string; isError: boolean; stage?: string }
+  | { type: "permission_denied"; name: string; message: string; stage?: string }
+  | { type: "stage_start"; stage: string }
+  | { type: "stage_output"; stage: string; artifact: string; path: string }
+  | { type: "context_loaded"; stage?: string; tokensEstimated: number; files: string[] }
+  | { type: "result"; finalText: string; turns: number; stage?: string };