pi-harness-runtime 0.10.43 → 1.1.1

package/packages/scheduler/test/scheduler.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Scheduler Tests
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { JsonRuntimeScheduler } from "../src/scheduler";
+
+const TMP = join(process.cwd(), ".test-scheduler-tmp");
+
+function scheduler(): JsonRuntimeScheduler {
+	return new JsonRuntimeScheduler(TMP);
+}
+
+beforeEach(() => {
+	rmSync(TMP, { force: true, recursive: true });
+	mkdirSync(TMP, { recursive: true });
+});
+
+describe("JsonRuntimeScheduler", () => {
+	describe("scheduleResume", () => {
+		it("writes a job to schedule.json", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-1", "2025-01-01T12:00:00Z", "test reason");
+			const jobs = await s.readAll();
+			expect(jobs).toHaveLength(1);
+			expect(jobs[0].jobId).toBe("job-1");
+			expect(jobs[0].status).toBe("scheduled");
+			expect(jobs[0].reason).toBe("test reason");
+		});
+
+		it("overwrites existing job with same ID", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-1", "2025-01-01T12:00:00Z", "reason A");
+			await s.scheduleResume("job-1", "2025-01-02T12:00:00Z", "reason B");
+			const jobs = await s.readAll();
+			expect(jobs).toHaveLength(1);
+			expect(jobs[0].reason).toBe("reason B");
+		});
+
+		it("keeps separate jobs distinct", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-A", "2025-01-01T12:00:00Z", "reason A");
+			await s.scheduleResume("job-B", "2025-01-02T12:00:00Z", "reason B");
+			const jobs = await s.readAll();
+			expect(jobs).toHaveLength(2);
+		});
+	});
+
+	describe("dueJobs", () => {
+		it("returns empty when nothing is due", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-1", "2099-12-31T23:59:59Z", "far future");
+			const due = await s.dueJobs(new Date("2025-01-01"));
+			expect(due).toHaveLength(0);
+		});
+
+		it("returns job when resumeAt has passed", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-1", "2024-01-01T12:00:00Z", "past");
+			const due = await s.dueJobs(new Date("2025-01-01"));
+			expect(due).toEqual(["job-1"]);
+		});
+
+		it("skips cancelled jobs", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-1", "2024-01-01T12:00:00Z", "cancelled");
+			await s.cancel("job-1");
+			const due = await s.dueJobs(new Date("2025-01-01"));
+			expect(due).toHaveLength(0);
+		});
+
+		it("returns multiple due jobs", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-A", "2024-01-01T12:00:00Z", "A");
+			await s.scheduleResume("job-B", "2024-01-02T12:00:00Z", "B");
+			await s.cancel("job-A");
+			const due = await s.dueJobs(new Date("2025-01-01"));
+			expect(due).toEqual(["job-B"]);
+		});
+
+		it("ignores resumeAt in the future", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-future", "2099-01-01T00:00:00Z", "too late");
+			const due = await s.dueJobs(new Date("2025-06-15"));
+			expect(due).toHaveLength(0);
+		});
+	});
+
+	describe("cancel", () => {
+		it("sets status to cancelled", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-1", "2024-01-01T00:00:00Z", "to cancel");
+			await s.cancel("job-1");
+			const jobs = await s.readAll();
+			expect(jobs).toHaveLength(1);
+			expect(jobs[0].status).toBe("cancelled");
+		});
+
+		it("no-op for unknown job", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-1", "2024-01-01T00:00:00Z", "exists");
+			await s.cancel("nonexistent");
+			const jobs = await s.readAll();
+			expect(jobs).toHaveLength(1);
+		});
+
+		it("cancelled job not returned by dueJobs", async () => {
+			const s = scheduler();
+			await s.scheduleResume("job-1", "2020-01-01T00:00:00Z", "was due");
+			await s.cancel("job-1");
+			const due = await s.dueJobs(new Date("2025-01-01"));
+			expect(due).toHaveLength(0);
+		});
+	});
+
+	describe("readAll", () => {
+		it("returns empty array for missing file", async () => {
+			const s = scheduler();
+			const jobs = await s.readAll();
+			expect(jobs).toEqual([]);
+		});
+	});
+});

package/packages/scheduler-adapter/README.md

@@ -0,0 +1,36 @@
+# Scheduler Adapter
+
+Pluggable scheduling backend for pi-harness-runtime.
+
+## Backends
+
+| Backend | File | When to use |
+|---|---|---|
+| Internal (in-process) | `internal.ts` | Local dev, testing, no system deps |
+| Cron | `cron.ts` | Linux/macOS with cron |
+| systemd | `systemd.ts` | Linux with systemd (recommended for autonomous) |
+
+## Usage
+
+```typescript
+import { SystemdAdapter } from "./index.js";
+
+const scheduler = new SystemdAdapter();
+await scheduler.install();
+await scheduler.schedule({
+  id: "nightly-compact",
+  taskTemplate: { kind: "compact" },
+  schedule: { kind: "cron", expression: "0 3 * * *" },
+});
+```
+
+## Adapter Interface
+
+```typescript
+interface SchedulerAdapter {
+  install(): Promise<void>;
+  schedule(task: ScheduledTask): Promise<void>;
+  unschedule(taskId: string): Promise<void>;
+  listScheduled(): Promise<ScheduledTask[]>;
+}
+```

package/packages/scheduler-adapter/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@pi/scheduler-adapter",
+  "version": "0.10.30",
+  "description": "Scheduler Adapter — cron, systemd, launchd, internal adapters for autonomous runtime (RFC-0101 §6)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "scheduler",
+    "cron",
+    "systemd",
+    "launchd",
+    "rfc-0101"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^7.0.2"
+  }
+}

package/packages/session/README.md

@@ -0,0 +1,273 @@
+# @pi/session
+
+Session management system for pi-harness-runtime with message history, token accounting, policy enforcement, and session persistence.
+
+## Features
+
+- **Session Lifecycle** - Create, suspend, resume, and close sessions
+- **Message History** - Full conversation history with search capabilities
+- **Token Accounting** - Track input/output tokens and costs per session
+- **Policy Engine** - Rate limiting, budget enforcement, and session policies
+- **Context Window** - Automatic management of context window size
+- **Persistence** - Sessions stored to disk with auto-save
+- **Event System** - Subscribe to session lifecycle events
+- **Auto-Cleanup** - Automatic expiration and idle timeout handling
+
+## Installation
+
+```bash
+npm install @pi/session
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { createSessionManager } from "@pi/session";
+
+const manager = createSessionManager({
+  rootDir: "./sessions",
+  sessionTtlMs: 24 * 60 * 60 * 1000, // 24 hours
+});
+
+// Create a new session
+const session = await manager.create("user-123", {
+  project: "my-project"
+});
+console.log(`Created session: ${session.id}`);
+
+// Add messages
+const userMessage = await manager.addMessage(session.id, {
+  role: "user",
+  content: "Hello, how are you?",
+  timestamp: new Date().toISOString(),
+});
+
+const assistantMessage = await manager.addMessage(session.id, {
+  role: "assistant",
+  content: "I'm doing well! How can I help you?",
+  timestamp: new Date().toISOString(),
+  tokens: 50,
+});
+
+// Get messages
+const messages = await manager.getMessages(session.id);
+console.log(`Session has ${messages.length} messages`);
+```
+
+### Session Lifecycle
+
+```typescript
+// Suspend a session
+await manager.suspend(session.id, "User requested pause");
+
+// Resume later
+const resumed = await manager.resume(session.id);
+console.log(`Session ${resumed?.status}`);
+
+// Close session
+await manager.end(session.id);
+```
+
+### Token Tracking
+
+```typescript
+// Update token usage
+await manager.updateTokenUsage(session.id, {
+  inputTokens: 1000,
+  outputTokens: 500,
+  inputCost: 0.01,
+  outputCost: 0.005,
+  totalCost: 0.015,
+  totalTokens: 1500,
+});
+
+// Get metrics
+const metrics = await manager.getMetrics(session.id);
+console.log(`Total cost: $${metrics?.totalCost}`);
+```
+
+### Policy Enforcement
+
+```typescript
+import { createPolicyEngine } from "@pi/session";
+
+const policy = createPolicyEngine({
+  maxRequestsPerMinute: 60,
+  maxCostPerSession: 10,
+  sessionBudget: 5,
+});
+
+// Check if action is allowed
+if (policy.canProceed(sessionId, "message")) {
+  // Proceed with action
+  policy.recordAction(sessionId, "message");
+} else {
+  const violation = policy.getViolationType(sessionId);
+  console.log(`Policy violation: ${violation}`);
+}
+```
+
+### Event System
+
+```typescript
+manager.on("session:created", (event) => {
+  console.log(`Session created: ${event.sessionId}`);
+});
+
+manager.on("message:added", (event) => {
+  console.log(`Message added to session: ${event.sessionId}`);
+});
+
+manager.on("policy:violation", (event) => {
+  console.log(`Policy violation: ${event.data?.violation}`);
+});
+
+manager.on("budget:exceeded", (event) => {
+  console.log(`Budget exceeded: $${event.data?.cost}`);
+});
+```
+
+### Context Window Management
+
+```typescript
+// Get messages that fit in a token budget
+const contextMessages = await manager.getMessagesForContext(
+  session.id,
+  4000 // Target tokens
+);
+console.log(`Got ${contextMessages.length} messages for 4k tokens`);
+```
+
+### Search Messages
+
+```typescript
+import { MessageSearch } from "@pi/session";
+
+const search = new MessageSearch();
+search.buildIndex(session.id, messages);
+
+const results = search.search({
+  sessionId: session.id,
+  role: "user",
+  contains: "help",
+  limit: 10,
+});
+
+console.log(`Found ${results.length} matching messages`);
+```
+
+## API Reference
+
+### SessionManager
+
+```typescript
+const manager = createSessionManager({
+  rootDir: string;           // Session storage directory
+  sessionTtlMs?: number;     // Session TTL (default: 24h)
+  maxIdleMs?: number;       // Max idle before suspend (default: 30m)
+  autoSaveIntervalMs?: number; // Auto-save interval (default: 5s)
+  maxMessagesPerSession?: number; // Max messages (default: 1000)
+  maxTokenBudget?: number;  // Token budget (default: 128000)
+  enableMetrics?: boolean;   // Enable metrics (default: true)
+  autoCleanup?: boolean;     // Auto-cleanup (default: true)
+  cleanupIntervalMs?: number; // Cleanup interval (default: 1h)
+});
+```
+
+### Methods
+
+```typescript
+// Create session
+await manager.create(userId, metadata?): Promise<Session>;
+
+// Get session summary
+await manager.get(sessionId): Promise<Session | null>;
+
+// Get full session context
+await manager.getContext(sessionId): Promise<SessionContext | null>;
+
+// End session
+await manager.end(sessionId): Promise<void>;
+
+// Suspend session
+await manager.suspend(sessionId, reason): Promise<void>;
+
+// Resume session
+await manager.resume(sessionId): Promise<Session | null>;
+
+// Add message
+await manager.addMessage(sessionId, message): Promise<Message | null>;
+
+// Get messages
+await manager.getMessages(sessionId, options?): Promise<Message[]>;
+
+// Get messages for context
+await manager.getMessagesForContext(sessionId, targetTokens): Promise<Message[]>;
+
+// Update token usage
+await manager.updateTokenUsage(sessionId, usage): Promise<void>;
+
+// Get metrics
+await manager.getMetrics(sessionId): Promise<SessionMetrics | null>;
+
+// List user sessions
+await manager.listByUser(userId): Promise<Session[]>;
+
+// Delete session
+await manager.delete(sessionId): Promise<void>;
+
+// Cleanup expired sessions
+await manager.cleanup(): Promise<number>;
+
+// Event listeners
+manager.on(eventType, listener): void;
+manager.off(eventType, listener): void;
+```
+
+### Event Types
+
+```typescript
+type SessionEventType =
+  | "session:created"
+  | "session:updated"
+  | "session:closed"
+  | "session:expired"
+  | "session:suspended"
+  | "session:resumed"
+  | "message:added"
+  | "policy:violation"
+  | "budget:exceeded";
+```
+
+### Storage Format
+
+Sessions are stored as JSON files:
+
+```
+sessions/
++-- index.json                    # Session index
++-- sessions/
+    +-- ab/
+        +-- cdef1234.../
+            +-- session.json      # Full session context
+```
+
+## Architecture
+
+```
++---------------------------------------------------------+
+|                    SessionManager                        |
+|  +-------------+  +-------------+  +-----------------+  |
+|  |   Manager   |  |   Policy    |  |     Store       |  |
+|  |             |--|   Engine    |--|                 |  |
+|  +-------------+  +-------------+  +-----------------+  |
+|         |                                      |        |
+|         ▼                                      ▼        |
+|  +-----------------+                +-----------------+|
+|  | ContextWindow   |                |    Disk         ||
+|  | Manager         |                |                 ||
+|  +-----------------+                +-----------------+|
++---------------------------------------------------------+
+```

package/packages/session/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pi/session",
+  "version": "0.10.30",
+  "description": "Session management system for pi-harness-runtime",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "test:watch": "bun test --watch"
+  },
+  "keywords": [
+    "pi",
+    "harness",
+    "runtime",
+    "session",
+    "management"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  }
+}