@tpsdev-ai/agent 0.1.0

package/bun.lock

@@ -0,0 +1,52 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@tpsdev-ai/agent",
+      "dependencies": {
+        "js-yaml": "^4.1.0",
+        "zod": "^3.24.0",
+      },
+      "devDependencies": {
+        "@biomejs/biome": "^2.4.4",
+        "@types/js-yaml": "^4.0.9",
+        "@types/node": "^22.0.0",
+        "typescript": "^5.7.0",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@2.4.4", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.4.4", "@biomejs/cli-darwin-x64": "2.4.4", "@biomejs/cli-linux-arm64": "2.4.4", "@biomejs/cli-linux-arm64-musl": "2.4.4", "@biomejs/cli-linux-x64": "2.4.4", "@biomejs/cli-linux-x64-musl": "2.4.4", "@biomejs/cli-win32-arm64": "2.4.4", "@biomejs/cli-win32-x64": "2.4.4" }, "bin": { "biome": "bin/biome" } }, "sha512-tigwWS5KfJf0cABVd52NVaXyAVv4qpUXOWJ1rxFL8xF1RVoeS2q/LK+FHgYoKMclJCuRoCWAPy1IXaN9/mS61Q=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.4.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-jZ+Xc6qvD6tTH5jM6eKX44dcbyNqJHssfl2nnwT6vma6B1sj7ZLTGIk6N5QwVBs5xGN52r3trk5fgd3sQ9We9A=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.4.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-Dh1a/+W+SUCXhEdL7TiX3ArPTFCQKJTI1mGncZNWfO+6suk+gYA4lNyJcBB+pwvF49uw0pEbUS49BgYOY4hzUg=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.4.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-V/NFfbWhsUU6w+m5WYbBenlEAz8eYnSqRMDMAW3K+3v0tYVkNyZn8VU0XPxk/lOqNXLSCCrV7FmV/u3SjCBShg=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.4.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-+sPAXq3bxmFwhVFJnSwkSF5Rw2ZAJMH3MF6C9IveAEOdSpgajPhoQhbbAK12SehN9j2QrHpk4J/cHsa/HqWaYQ=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.4.4", "", { "os": "linux", "cpu": "x64" }, "sha512-R4+ZCDtG9kHArasyBO+UBD6jr/FcFCTH8QkNTOCu0pRJzCWyWC4EtZa2AmUZB5h3e0jD7bRV2KvrENcf8rndBg=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.4.4", "", { "os": "linux", "cpu": "x64" }, "sha512-gGvFTGpOIQDb5CQ2VC0n9Z2UEqlP46c4aNgHmAMytYieTGEcfqhfCFnhs6xjt0S3igE6q5GLuIXtdQt3Izok+g=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.4.4", "", { "os": "win32", "cpu": "arm64" }, "sha512-trzCqM7x+Gn832zZHgr28JoYagQNX4CZkUZhMUac2YxvvyDRLJDrb5m9IA7CaZLlX6lTQmADVfLEKP1et1Ma4Q=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.4.4", "", { "os": "win32", "cpu": "x64" }, "sha512-gnOHKVPFAAPrpoPt2t+Q6FZ7RPry/FDV3GcpU53P3PtLNnQjBmKyN2Vh/JtqXet+H4pme8CC76rScwdjDcT1/A=="],
+
+    "@types/js-yaml": ["@types/js-yaml@4.0.9", "", {}, "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg=="],
+
+    "@types/node": ["@types/node@22.19.11", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-BH7YwL6rA93ReqeQS1c4bsPpcfOmJasG+Fkr6Y59q83f9M1WcBRHR2vM+P9eOisYRcN3ujQoiZY8uk5W+1WL8w=="],
+
+    "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
+
+    "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
+
+    "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@tpsdev-ai/agent",
+  "version": "0.1.0",
+  "description": "Native TPS Agent Runtime — headless, mail-driven, nono-sandboxed",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "bun test",
+    "lint": "biome lint ./src",
+    "lint:ci": "biome lint ./src --max-diagnostics=200"
+  },
+  "keywords": ["agents", "tps", "runtime", "mail-driven"],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "author": "tpsdev-ai",
+  "publishConfig": { "access": "public" }
+}

package/src/governance/boundary.ts

@@ -0,0 +1,37 @@
+/**
+ * BoundaryManager discovers nono profile constraints at boot and communicates
+ * allowed capabilities to the ToolRegistry.
+ *
+ * NOTE: The system prompt is NOT a security boundary. Hard nono syscall/network
+ * filters and pre-execution checks in ToolRegistry are the actual enforcement.
+ */
+export class BoundaryManager {
+  private allowedNetworkHosts: Set<string> = new Set();
+  private allowedPaths: Set<string> = new Set();
+
+  addNetworkHost(host: string): void {
+    this.allowedNetworkHosts.add(host);
+  }
+
+  addPath(path: string): void {
+    this.allowedPaths.add(path);
+  }
+
+  isNetworkAllowed(host: string): boolean {
+    return this.allowedNetworkHosts.has(host) || this.allowedNetworkHosts.has("*");
+  }
+
+  isPathAllowed(path: string): boolean {
+    for (const allowed of this.allowedPaths) {
+      if (path === allowed || path.startsWith(allowed + "/")) return true;
+    }
+    return false;
+  }
+
+  /** Returns a human-readable capabilities summary for the LLM system prompt. */
+  describeCapabilities(): string {
+    const nets = [...this.allowedNetworkHosts].join(", ") || "none";
+    const paths = [...this.allowedPaths].join(", ") || "none";
+    return `Network access: ${nets}\nFilesystem access: ${paths}`;
+  }
+}

package/src/governance/review-gate.ts

@@ -0,0 +1,34 @@
+import type { MailClient } from "../io/mail.js";
+
+/** Actions that must pause for human-in-the-loop approval. */
+const HIGH_RISK_ACTIONS = new Set([
+  "git_push",
+  "package_install",
+  "file_delete",
+  "exec_privileged",
+]);
+
+export class ReviewGate {
+  constructor(
+    private readonly mail: MailClient,
+    private readonly approverAddress: string
+  ) {}
+
+  isHighRisk(toolName: string): boolean {
+    return HIGH_RISK_ACTIONS.has(toolName);
+  }
+
+  async requestApproval(toolName: string, args: Record<string, unknown>): Promise<void> {
+    const body = JSON.stringify(
+      {
+        type: "approval_request",
+        tool: toolName,
+        args,
+        requestedAt: new Date().toISOString(),
+      },
+      null,
+      2
+    );
+    await this.mail.sendMail(this.approverAddress, body);
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+// Public API for @tpsdev-ai/agent
+
+// Runtime
+export { AgentRuntime } from "./runtime/agent.js";
+export { EventLoop } from "./runtime/event-loop.js";
+export type { AgentConfig, LLMConfig, AgentState } from "./runtime/types.js";
+
+// I/O
+export { MailClient } from "./io/mail.js";
+export type { MailMessage } from "./io/mail.js";
+export { MemoryStore } from "./io/memory.js";
+export type { MemoryEvent } from "./io/memory.js";
+export { ContextManager } from "./io/context.js";
+
+// LLM
+export { ProviderManager } from "./llm/provider.js";
+export type { CompletionRequest, CompletionResponse } from "./llm/provider.js";
+
+// Tools
+export { ToolRegistry } from "./tools/registry.js";
+export type { Tool } from "./tools/registry.js";
+
+// Governance
+export { BoundaryManager } from "./governance/boundary.js";
+export { ReviewGate } from "./governance/review-gate.js";

package/src/io/context.ts

@@ -0,0 +1,40 @@
+import type { MemoryStore, MemoryEvent } from "./memory.js";
+
+/**
+ * Sliding window context manager with compaction.
+ *
+ * When token usage approaches the configured window, the oldest 50%
+ * of events are summarised into a dense state blob to preserve headroom
+ * without losing history.
+ */
+export class ContextManager {
+  constructor(
+    private readonly memory: MemoryStore,
+    private readonly windowTokens: number
+  ) {}
+
+  /** Return recent events that fit within the token window. */
+  getWindow(): MemoryEvent[] {
+    const all = this.memory.readAll();
+    if (all.length === 0) return [];
+
+    // Simple sliding-window: walk from newest, accumulate until budget
+    const budget = this.windowTokens * 4; // chars ≈ tokens * 4
+    let budget_remaining = budget;
+    const window: MemoryEvent[] = [];
+
+    for (let i = all.length - 1; i >= 0; i--) {
+      const serialized = JSON.stringify(all[i]);
+      if (serialized.length > budget_remaining) break;
+      window.unshift(all[i]!);
+      budget_remaining -= serialized.length;
+    }
+
+    return window;
+  }
+
+  /** Returns true if compaction is needed (>80% of window used). */
+  needsCompaction(): boolean {
+    return this.memory.estimatedTokenCount() > this.windowTokens * 0.8;
+  }
+}

package/src/io/mail.ts

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface MailMessage {
+  filename: string;
+  body: string;
+  receivedAt: Date;
+}
+
+/**
+ * Maildir-compatible mail client.
+ * Reads from mailDir/inbox/new and moves processed messages to mailDir/inbox/cur.
+ * Writes outgoing mail to mailDir/outbox/new.
+ */
+export class MailClient {
+  private inboxNew: string;
+  private inboxCur: string;
+  private outboxNew: string;
+
+  constructor(public readonly mailDir: string) {
+    this.inboxNew = join(mailDir, "inbox", "new");
+    this.inboxCur = join(mailDir, "inbox", "cur");
+    this.outboxNew = join(mailDir, "outbox", "new");
+    // Ensure directories exist
+    for (const dir of [this.inboxNew, this.inboxCur, this.outboxNew]) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /** Return all messages in inbox/new and move them to inbox/cur. */
+  async checkNewMail(): Promise<MailMessage[]> {
+    if (!existsSync(this.inboxNew)) return [];
+
+    const files = readdirSync(this.inboxNew).filter((f) => !f.startsWith(".") && !f.includes("/") && !f.includes("\\"));
+    const messages: MailMessage[] = [];
+
+    for (const file of files) {
+      const srcPath = join(this.inboxNew, file);
+      const dstPath = join(this.inboxCur, file);
+      const body = readFileSync(srcPath, "utf-8");
+      renameSync(srcPath, dstPath);
+      messages.push({ filename: file, body, receivedAt: new Date() });
+    }
+
+    return messages;
+  }
+
+  /** Write a message to outbox/new for relay delivery. */
+  async sendMail(to: string, body: string): Promise<void> {
+    const { writeFileSync } = await import("node:fs");
+    const filename = `${Date.now()}-${Math.random().toString(36).slice(2)}.json`;
+    writeFileSync(
+      join(this.outboxNew, filename),
+      JSON.stringify({ to, body, sentAt: new Date().toISOString() }, null, 2),
+      "utf-8"
+    );
+  }
+}

package/src/io/memory.ts

@@ -0,0 +1,59 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, openSync, readSync, closeSync } from "node:fs";
+import { dirname } from "node:path";
+
+export interface MemoryEvent {
+  type: string;
+  ts: string;
+  data: unknown;
+}
+
+/**
+ * Append-only JSONL memory store. Each event is a line of JSON.
+ * Provides full audit trail of agent actions and LLM interactions.
+ */
+export class MemoryStore {
+  constructor(public readonly memoryPath: string) {
+    mkdirSync(dirname(memoryPath), { recursive: true });
+  }
+
+  append(event: MemoryEvent): void {
+    appendFileSync(this.memoryPath, JSON.stringify(event) + "\n", "utf-8");
+  }
+
+  readAll(maxBytes = 1024 * 1024): MemoryEvent[] {
+    if (!existsSync(this.memoryPath)) return [];
+    
+    const stat = statSync(this.memoryPath);
+    if (stat.size === 0) return [];
+    
+    const size = Math.min(stat.size, maxBytes);
+    const pos = Math.max(0, stat.size - size);
+    
+    const fd = openSync(this.memoryPath, "r");
+    const buffer = Buffer.alloc(size);
+    readSync(fd, buffer, 0, size, pos);
+    closeSync(fd);
+    
+    const content = buffer.toString("utf-8");
+    const lines = content.split("\n");
+    if (pos > 0) lines.shift(); // drop partial first line
+    
+    return lines
+      .filter(Boolean)
+      .map((line) => {
+        try {
+          return JSON.parse(line) as MemoryEvent;
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean) as MemoryEvent[];
+  }
+
+  /** Count approximate token length (4 chars ≈ 1 token) */
+  estimatedTokenCount(): number {
+    if (!existsSync(this.memoryPath)) return 0;
+    const stat = statSync(this.memoryPath);
+    return Math.ceil(stat.size / 4);
+  }
+}

package/src/llm/provider.ts

@@ -0,0 +1,126 @@
+import type { LLMConfig } from "../runtime/types.js";
+
+export interface CompletionRequest {
+  systemPrompt?: string;
+  messages: Array<{ role: "user" | "assistant"; content: string }>;
+  maxTokens?: number;
+}
+
+export interface CompletionResponse {
+  content: string;
+  inputTokens: number;
+  outputTokens: number;
+}
+
+/**
+ * Routes completion requests to the appropriate provider.
+ * Supports Anthropic, Google, and local Ollama.
+ */
+export class ProviderManager {
+  constructor(private readonly config: LLMConfig) {}
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    switch (this.config.provider) {
+      case "anthropic":
+        return this.completeAnthropic(request);
+      case "google":
+        return this.completeGoogle(request);
+      case "ollama":
+        return this.completeOllama(request);
+      default:
+        throw new Error(`Unsupported provider: ${this.config.provider}`);
+    }
+  }
+
+  private async completeAnthropic(request: CompletionRequest): Promise<CompletionResponse> {
+    const apiKey = this.config.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) throw new Error("ANTHROPIC_API_KEY not set");
+
+    const res = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model: this.config.model,
+        max_tokens: request.maxTokens ?? 2048,
+        system: request.systemPrompt,
+        messages: request.messages,
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`Anthropic API error: ${res.status} ${await res.text()}`);
+    }
+
+    const data = (await res.json()) as any;
+    return {
+      content: data.content?.[0]?.text ?? "",
+      inputTokens: data.usage?.input_tokens ?? 0,
+      outputTokens: data.usage?.output_tokens ?? 0,
+    };
+  }
+
+  private async completeGoogle(request: CompletionRequest): Promise<CompletionResponse> {
+    const apiKey = this.config.apiKey ?? process.env.GOOGLE_API_KEY;
+    if (!apiKey) throw new Error("GOOGLE_API_KEY not set");
+
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${this.config.model}:generateContent?key=${apiKey}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        contents: request.messages.map((m) => ({
+          role: m.role === "assistant" ? "model" : "user",
+          parts: [{ text: m.content }],
+        })),
+        systemInstruction: request.systemPrompt
+          ? { parts: [{ text: request.systemPrompt }] }
+          : undefined,
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`Google API error: ${res.status} ${await res.text()}`);
+    }
+
+    const data = (await res.json()) as any;
+    const text = data.candidates?.[0]?.content?.parts?.[0]?.text ?? "";
+    const usage = data.usageMetadata ?? {};
+    return {
+      content: text,
+      inputTokens: usage.promptTokenCount ?? 0,
+      outputTokens: usage.candidatesTokenCount ?? 0,
+    };
+  }
+
+  private async completeOllama(request: CompletionRequest): Promise<CompletionResponse> {
+    const baseUrl = this.config.baseUrl ?? "http://localhost:11434";
+    const systemMsg = request.systemPrompt
+      ? [{ role: "system" as const, content: request.systemPrompt }]
+      : [];
+
+    const res = await fetch(`${baseUrl}/api/chat`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: this.config.model,
+        messages: [...systemMsg, ...request.messages],
+        stream: false,
+      }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`Ollama API error: ${res.status} ${await res.text()}`);
+    }
+
+    const data = (await res.json()) as any;
+    return {
+      content: data.message?.content ?? "",
+      inputTokens: data.prompt_eval_count ?? 0,
+      outputTokens: data.eval_count ?? 0,
+    };
+  }
+}

package/src/runtime/agent.ts

@@ -0,0 +1,26 @@
+import type { AgentConfig } from "./types.js";
+import { EventLoop } from "./event-loop.js";
+import { MailClient } from "../io/mail.js";
+import { MemoryStore } from "../io/memory.js";
+import { ContextManager } from "../io/context.js";
+import { ProviderManager } from "../llm/provider.js";
+
+export class AgentRuntime {
+  private loop: EventLoop;
+
+  constructor(public readonly config: AgentConfig) {
+    const mail = new MailClient(config.mailDir);
+    const memory = new MemoryStore(config.memoryPath);
+    const context = new ContextManager(memory, config.contextWindowTokens ?? 8_000);
+    const provider = new ProviderManager(config.llm);
+    this.loop = new EventLoop({ config, mail, memory, context, provider });
+  }
+
+  async start(): Promise<void> {
+    await this.loop.run();
+  }
+
+  async stop(): Promise<void> {
+    await this.loop.stop();
+  }
+}

package/src/runtime/event-loop.ts

@@ -0,0 +1,76 @@
+import type { AgentConfig, AgentState } from "./types.js";
+import type { MailClient } from "../io/mail.js";
+import type { MemoryStore } from "../io/memory.js";
+import type { ContextManager } from "../io/context.js";
+import type { ProviderManager } from "../llm/provider.js";
+
+interface EventLoopDeps {
+  config: AgentConfig;
+  mail: MailClient;
+  memory: MemoryStore;
+  context: ContextManager;
+  provider: ProviderManager;
+}
+
+export class EventLoop {
+  private state: AgentState = "idle";
+  private running = false;
+
+  constructor(private readonly deps: EventLoopDeps) {}
+
+  async run(): Promise<void> {
+    this.running = true;
+    this.state = "idle";
+
+    while (this.running) {
+      const messages = await this.deps.mail.checkNewMail();
+
+      if (messages.length === 0) {
+        // No work — sleep briefly before next poll
+        await sleep(500);
+        continue;
+      }
+
+      for (const msg of messages) {
+        if (!this.running) break;
+
+        this.state = "processing";
+
+        try {
+          await this.processMessage(msg);
+        } catch (err) {
+          // Log errors to memory and continue rather than crashing the loop
+          await this.deps.memory.append({
+            type: "error",
+            ts: new Date().toISOString(),
+            data: String(err),
+          });
+        }
+
+        this.state = "idle";
+      }
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    this.state = "stopped";
+  }
+
+  getState(): AgentState {
+    return this.state;
+  }
+
+  private async processMessage(msg: unknown): Promise<void> {
+    // Stub: real implementation builds prompt, calls LLM, handles tool calls
+    await this.deps.memory.append({
+      type: "message",
+      ts: new Date().toISOString(),
+      data: msg,
+    });
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/runtime/types.ts

@@ -0,0 +1,30 @@
+export interface LLMConfig {
+  provider: "anthropic" | "google" | "ollama";
+  model: string;
+  apiKey?: string;
+  baseUrl?: string;
+}
+
+export interface AgentConfig {
+  /** Agent identifier from tps.yaml */
+  agentId: string;
+  /** Human-readable name */
+  name: string;
+  /** Maildir root: ~/mail/inbox, ~/mail/outbox */
+  mailDir: string;
+  /** JSONL memory file path */
+  memoryPath: string;
+  /** Target token context window (for compaction) */
+  contextWindowTokens?: number;
+  /** LLM provider config */
+  llm: LLMConfig;
+  /** System prompt override */
+  systemPrompt?: string;
+}
+
+/** Runtime state machine states */
+export type AgentState =
+  | "idle"
+  | "processing"
+  | "awaiting_approval"
+  | "stopped";

package/src/tools/registry.ts

@@ -0,0 +1,33 @@
+export interface Tool {
+  name: string;
+  description: string;
+  parameters: Record<string, { type: string; description: string; required?: boolean }>;
+  execute(args: Record<string, unknown>): Promise<string>;
+}
+
+/**
+ * Central registry for native TPS agent tools.
+ * Only tools explicitly registered (and allowed by the nono profile)
+ * are exposed to the LLM.
+ */
+export class ToolRegistry {
+  private tools = new Map<string, Tool>();
+
+  register(tool: Tool): void {
+    this.tools.set(tool.name, tool);
+  }
+
+  get(name: string): Tool | undefined {
+    return this.tools.get(name);
+  }
+
+  list(): Tool[] {
+    return Array.from(this.tools.values());
+  }
+
+  async execute(name: string, args: Record<string, unknown>): Promise<string> {
+    const tool = this.tools.get(name);
+    if (!tool) throw new Error(`Unknown tool: ${name}`);
+    return tool.execute(args);
+  }
+}

package/test/governance.test.ts

@@ -0,0 +1,102 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { BoundaryManager } from "../src/governance/boundary.js";
+import { ReviewGate } from "../src/governance/review-gate.js";
+import { MailClient } from "../src/io/mail.js";
+import { ToolRegistry } from "../src/tools/registry.js";
+
+describe("BoundaryManager", () => {
+  test("allows registered network host", () => {
+    const mgr = new BoundaryManager();
+    mgr.addNetworkHost("api.anthropic.com");
+    expect(mgr.isNetworkAllowed("api.anthropic.com")).toBe(true);
+    expect(mgr.isNetworkAllowed("evil.com")).toBe(false);
+  });
+
+  test("wildcard allows any host", () => {
+    const mgr = new BoundaryManager();
+    mgr.addNetworkHost("*");
+    expect(mgr.isNetworkAllowed("api.anthropic.com")).toBe(true);
+  });
+
+  test("allows registered path prefix", () => {
+    const mgr = new BoundaryManager();
+    mgr.addPath("/workspace");
+    expect(mgr.isPathAllowed("/workspace/src")).toBe(true);
+    expect(mgr.isPathAllowed("/etc/passwd")).toBe(false);
+  });
+
+  test("describeCapabilities returns readable string", () => {
+    const mgr = new BoundaryManager();
+    mgr.addNetworkHost("api.anthropic.com");
+    mgr.addPath("/workspace");
+    const desc = mgr.describeCapabilities();
+    expect(desc).toContain("api.anthropic.com");
+    expect(desc).toContain("/workspace");
+  });
+});
+
+describe("ReviewGate", () => {
+  let tmpDir: string;
+  let mail: MailClient;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "tps-gate-test-"));
+    mail = new MailClient(tmpDir);
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("identifies high-risk tools", () => {
+    const gate = new ReviewGate(mail, "host@tps");
+    expect(gate.isHighRisk("git_push")).toBe(true);
+    expect(gate.isHighRisk("file_delete")).toBe(true);
+    expect(gate.isHighRisk("fs_read")).toBe(false);
+  });
+
+  test("requestApproval sends mail to approver", async () => {
+    const gate = new ReviewGate(mail, "host@tps");
+    await gate.requestApproval("git_push", { branch: "main" });
+    const { readdirSync } = await import("node:fs");
+    const outbox = join(tmpDir, "outbox", "new");
+    expect(readdirSync(outbox).length).toBe(1);
+  });
+});
+
+describe("ToolRegistry", () => {
+  test("registers and executes a tool", async () => {
+    const registry = new ToolRegistry();
+    registry.register({
+      name: "echo",
+      description: "Echo input",
+      parameters: { input: { type: "string", description: "text to echo" } },
+      async execute(args) {
+        return String(args.input);
+      },
+    });
+
+    const result = await registry.execute("echo", { input: "hello" });
+    expect(result).toBe("hello");
+  });
+
+  test("throws for unknown tool", async () => {
+    const registry = new ToolRegistry();
+    await expect(registry.execute("noop", {})).rejects.toThrow("Unknown tool: noop");
+  });
+
+  test("lists registered tools", () => {
+    const registry = new ToolRegistry();
+    registry.register({
+      name: "echo",
+      description: "Echo input",
+      parameters: {},
+      async execute() { return ""; },
+    });
+    expect(registry.list().length).toBe(1);
+    expect(registry.list()[0]!.name).toBe("echo");
+  });
+});

package/test/io.test.ts

@@ -0,0 +1,105 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync, join as pathJoin } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { MailClient } from "../src/io/mail.js";
+import { MemoryStore } from "../src/io/memory.js";
+import { ContextManager } from "../src/io/context.js";
+
+describe("MailClient", () => {
+  let tmpDir: string;
+  let client: MailClient;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "tps-mail-test-"));
+    client = new MailClient(tmpDir);
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("creates required maildir directories on construction", () => {
+    const { existsSync } = require("node:fs");
+    expect(existsSync(join(tmpDir, "inbox", "new"))).toBe(true);
+    expect(existsSync(join(tmpDir, "inbox", "cur"))).toBe(true);
+    expect(existsSync(join(tmpDir, "outbox", "new"))).toBe(true);
+  });
+
+  test("checkNewMail returns empty when inbox is empty", async () => {
+    const msgs = await client.checkNewMail();
+    expect(msgs).toEqual([]);
+  });
+
+  test("checkNewMail returns and moves messages from new to cur", async () => {
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(join(tmpDir, "inbox", "new", "test-1.json"), "hello world", "utf-8");
+
+    const msgs = await client.checkNewMail();
+    expect(msgs.length).toBe(1);
+    expect(msgs[0]!.body).toBe("hello world");
+
+    // File should now be in cur
+    const { existsSync } = await import("node:fs");
+    expect(existsSync(join(tmpDir, "inbox", "new", "test-1.json"))).toBe(false);
+    expect(existsSync(join(tmpDir, "inbox", "cur", "test-1.json"))).toBe(true);
+  });
+
+  test("sendMail writes a file to outbox/new", async () => {
+    await client.sendMail("host@tps", "hello from agent");
+
+    const { readdirSync } = await import("node:fs");
+    const files = readdirSync(join(tmpDir, "outbox", "new"));
+    expect(files.length).toBe(1);
+  });
+});
+
+describe("MemoryStore", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "tps-mem-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("append and readAll round-trip", () => {
+    const store = new MemoryStore(join(tmpDir, "memory.jsonl"));
+    store.append({ type: "test", ts: "2025-01-01T00:00:00Z", data: "hello" });
+    const all = store.readAll();
+    expect(all.length).toBe(1);
+    expect(all[0]!.type).toBe("test");
+    expect(all[0]!.data).toBe("hello");
+  });
+
+  test("readAll returns empty array for missing file", () => {
+    const store = new MemoryStore(join(tmpDir, "missing.jsonl"));
+    expect(store.readAll()).toEqual([]);
+  });
+});
+
+describe("ContextManager", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "tps-ctx-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("getWindow returns empty for empty memory", () => {
+    const store = new MemoryStore(join(tmpDir, "mem.jsonl"));
+    const ctx = new ContextManager(store, 1000);
+    expect(ctx.getWindow()).toEqual([]);
+  });
+
+  test("needsCompaction is false for empty memory", () => {
+    const store = new MemoryStore(join(tmpDir, "mem.jsonl"));
+    const ctx = new ContextManager(store, 1000);
+    expect(ctx.needsCompaction()).toBe(false);
+  });
+});

package/test/runtime.test.ts

@@ -0,0 +1,45 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { AgentRuntime } from "../src/runtime/agent.js";
+import type { AgentConfig } from "../src/runtime/types.js";
+
+describe("AgentRuntime", () => {
+  let tmpDir: string;
+  let config: AgentConfig;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "tps-agent-test-"));
+    config = {
+      agentId: "test-agent",
+      name: "Test Agent",
+      mailDir: join(tmpDir, "mail"),
+      memoryPath: join(tmpDir, "memory.jsonl"),
+      contextWindowTokens: 1000,
+      llm: { provider: "anthropic", model: "claude-3-haiku-20240307" },
+    };
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("can be instantiated with a valid config", () => {
+    const runtime = new AgentRuntime(config);
+    expect(runtime).toBeDefined();
+    expect(runtime.config.agentId).toBe("test-agent");
+    expect(runtime.config.name).toBe("Test Agent");
+  });
+
+  test("start() returns when stop() is called", async () => {
+    const runtime = new AgentRuntime(config);
+
+    // Start and stop after 50ms to avoid infinite loop
+    const startPromise = runtime.start();
+    setTimeout(() => runtime.stop(), 50);
+    await startPromise;
+    // Just verify it completes without throwing
+    expect(true).toBe(true);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}