@trama-dev/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 trama contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @trama-dev/runtime
+
+The runtime behind [trama](https://github.com/NaNhkNaN/trama) — where the program is the orchestration.
+
+This package has two surfaces:
+
+**Client** — what trama-generated programs import. 9 functions, nothing else.
+
+```typescript
+import { ctx, agent, tools } from "@trama-dev/runtime";
+
+const data = await tools.read("input.csv");
+const report = await agent.ask(`Analyze this:\n${data}`);
+await tools.write("report.md", report);
+await ctx.done();
+```
+
+**Runner** — what the CLI and programmatic callers use to execute programs.
+
+```typescript
+import { runProgram, createProject } from "@trama-dev/runtime/runner";
+```
+
+See the [main README](https://github.com/NaNhkNaN/trama) for the full picture.

package/dist/agent.d.ts

@@ -0,0 +1,3 @@
+import type { Agent } from "./types.js";
+import type { PiAdapter } from "./pi-adapter.js";
+export declare function createAgent(adapter: PiAdapter): Agent;

package/dist/agent.js

@@ -0,0 +1,55 @@
+/**
+ * Minimal shape validation.
+ * Checks all schema keys exist and values match declared primitive types.
+ * The part after ":" is a description and is ignored during validation.
+ */
+function validateShape(result, schema) {
+    if (typeof result !== "object" || result === null)
+        return "response is not an object";
+    const obj = result;
+    for (const [key, typeDesc] of Object.entries(schema)) {
+        if (!(key in obj))
+            return `missing key: ${key}`;
+        const expectedType = typeDesc.split(":")[0].trim();
+        const actual = typeof obj[key];
+        if (expectedType === "string" && actual !== "string")
+            return `${key}: expected string, got ${actual}`;
+        if (expectedType === "number" && actual !== "number")
+            return `${key}: expected number, got ${actual}`;
+        if (expectedType === "boolean" && actual !== "boolean")
+            return `${key}: expected boolean, got ${actual}`;
+    }
+    return null;
+}
+export function createAgent(adapter) {
+    return {
+        async ask(prompt, options) {
+            return adapter.ask(prompt, options);
+        },
+        async generate(input) {
+            const schemaInstruction = `Respond with ONLY a JSON object matching this shape:\n${JSON.stringify(input.schema, null, 2)}\nNo markdown. No explanation. Just the JSON.`;
+            const fullPrompt = `${input.prompt}\n\n${schemaInstruction}`;
+            const attempt = async (p) => {
+                const response = await adapter.ask(p, { system: input.system });
+                const cleaned = response
+                    .trim()
+                    .replace(/^```json\s*/i, "")
+                    .replace(/^```\s*/, "")
+                    .replace(/\s*```$/, "")
+                    .trim();
+                const parsed = JSON.parse(cleaned);
+                const error = validateShape(parsed, input.schema);
+                if (error)
+                    throw new Error(`Schema validation failed: ${error}`);
+                return parsed;
+            };
+            try {
+                return await attempt(fullPrompt);
+            }
+            catch (firstError) {
+                const retryPrompt = `Your previous response failed validation: ${firstError}.\nTry again.\n\n${fullPrompt}`;
+                return await attempt(retryPrompt);
+            }
+        }
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,4 @@
+import type { Ctx, Agent, Tools } from "./types.js";
+export declare const ctx: Ctx;
+export declare const agent: Agent;
+export declare const tools: Tools;

package/dist/client.js

@@ -0,0 +1,53 @@
+// @trama-dev/runtime client — this is what program.ts imports.
+// Thin HTTP wrapper that calls the runner's IPC server.
+const PORT = process.env.TRAMA_PORT;
+if (!PORT) {
+    throw new Error("@trama-dev/runtime must be executed via `trama run`. " +
+        "Direct execution is not supported (TRAMA_PORT env var missing).");
+}
+if (!process.env.TRAMA_INPUT) {
+    throw new Error("@trama-dev/runtime: TRAMA_INPUT env var missing. " +
+        "This program must be launched by the trama runner.");
+}
+const BASE = `http://127.0.0.1:${PORT}`;
+async function call(endpoint, body) {
+    const res = await fetch(`${BASE}${endpoint}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw new Error(`trama runtime error: ${await res.text()}`);
+    return res.json();
+}
+let doneCalled = false;
+export const ctx = {
+    input: JSON.parse(process.env.TRAMA_INPUT),
+    state: JSON.parse(process.env.TRAMA_STATE ?? "{}"),
+    iteration: parseInt(process.env.TRAMA_ITERATION ?? "0"),
+    maxIterations: parseInt(process.env.TRAMA_MAX_ITERATIONS ?? "100"),
+    async log(msg, data) {
+        await call("/ctx/log", { message: msg, data });
+    },
+    async checkpoint() {
+        await call("/ctx/checkpoint", { state: ctx.state });
+        ctx.iteration += 1;
+    },
+    async done(result) {
+        if (doneCalled)
+            return;
+        await call("/ctx/done", { state: ctx.state, result });
+        doneCalled = true;
+        ctx.iteration += 1;
+    },
+};
+export const agent = {
+    ask: (prompt, opts) => call("/agent/ask", { prompt, ...opts }).then(r => r.result),
+    generate: (input) => call("/agent/generate", input).then(r => r.result),
+};
+export const tools = {
+    read: (path) => call("/tools/read", { path }).then(r => r.result),
+    write: (path, content) => call("/tools/write", { path, content }).then(r => r.result),
+    shell: (cmd, opts) => call("/tools/shell", { command: cmd, ...opts }),
+    fetch: (url, opts) => call("/tools/fetch", { url, ...opts }),
+};

package/dist/context.d.ts

@@ -0,0 +1,4 @@
+import type { Ctx } from "./types.js";
+export declare function createContext(projectDir: string, initialState: Record<string, unknown>, options?: {
+    maxIterations?: number;
+}): Ctx;

package/dist/context.js

@@ -0,0 +1,79 @@
+import { readFileSync, writeFileSync, appendFileSync } from "fs";
+import { join } from "path";
+/**
+ * Recursively check that a value is strictly JSON-serializable.
+ * Throws TypeError with the path to the offending value.
+ *
+ * Uses a stack (ancestor chain) instead of a flat set so that shared-but-
+ * non-circular structures like { a: shared, b: shared } pass validation.
+ */
+function assertSerializable(value, path, ancestors = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError(`${path} is not JSON-serializable (${value})`);
+        }
+        return;
+    }
+    if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+        throw new TypeError(`${path} is not JSON-serializable (${typeof value})`);
+    }
+    if (ancestors.has(value)) {
+        throw new TypeError(`${path} contains a circular reference`);
+    }
+    ancestors.add(value);
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            assertSerializable(value[i], `${path}[${i}]`, ancestors);
+        }
+        ancestors.delete(value);
+        return;
+    }
+    if (Object.getPrototypeOf(value) !== Object.prototype) {
+        const name = value.constructor?.name ?? "unknown";
+        throw new TypeError(`${path} is not a plain object (${name})`);
+    }
+    for (const [k, v] of Object.entries(value)) {
+        assertSerializable(v, `${path}.${k}`, ancestors);
+    }
+    ancestors.delete(value);
+}
+export function createContext(projectDir, initialState, options) {
+    const logsPath = join(projectDir, "logs", "latest.jsonl");
+    const statePath = join(projectDir, "state.json");
+    const meta = JSON.parse(readFileSync(join(projectDir, "meta.json"), "utf-8"));
+    let doneCalled = false;
+    let doneLogged = false;
+    return {
+        input: meta.input,
+        state: { ...initialState },
+        iteration: typeof initialState.__trama_iteration === "number"
+            && Number.isFinite(initialState.__trama_iteration)
+            ? initialState.__trama_iteration : 0,
+        maxIterations: options?.maxIterations ?? 100,
+        async log(message, data) {
+            const entry = { ts: Date.now(), message, data: data ?? null };
+            appendFileSync(logsPath, JSON.stringify(entry) + "\n");
+            console.log(`[trama] ${message}`);
+        },
+        async checkpoint() {
+            assertSerializable(this.state, "ctx.state");
+            const nextIteration = this.iteration + 1;
+            this.state.__trama_iteration = nextIteration;
+            writeFileSync(statePath, JSON.stringify(this.state, null, 2));
+            this.iteration = nextIteration;
+        },
+        async done(result) {
+            if (doneCalled)
+                return;
+            if (result && !doneLogged) {
+                await this.log("done", result);
+                doneLogged = true;
+            }
+            await this.checkpoint();
+            doneCalled = true;
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { runProgram } from "./runner.js";
+export declare function validateProjectName(name: string): void;
+export declare function createProject(name: string, prompt: string, options?: {
+    model?: string;
+}): Promise<void>;
+export declare function updateProject(name: string, prompt: string): Promise<void>;
+export declare function listProjects(): Promise<void>;
+export declare function showLogs(name: string): Promise<void>;

package/dist/index.js

@@ -0,0 +1,215 @@
+// @trama-dev/runtime runner surface — exported via "@trama-dev/runtime/runner"
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, copyFileSync, appendFileSync, statSync, rmSync, cpSync, mkdtempSync } from "fs";
+import { join } from "path";
+import { homedir, tmpdir } from "os";
+import { PiAdapter } from "./pi-adapter.js";
+import { loadConfig, loadState, smokeRunAndRepair, copyToHistory, RUNTIME_TYPES, PI_VERSION } from "./runner.js";
+export { runProgram } from "./runner.js";
+// --- Example programs (included in system prompt during create/update) ---
+const EXAMPLE_PROGRAMS = `// Example A: Simple (single action)
+import { ctx, tools } from "@trama-dev/runtime";
+
+const content = "# Hello World\\nGenerated at " + new Date().toISOString();
+await tools.write("hello.md", content);
+await ctx.log("wrote hello.md");
+await ctx.done();
+
+// Example B: Medium (LLM + tools)
+import { ctx, agent, tools } from "@trama-dev/runtime";
+
+const data = await tools.read(ctx.input.args.file as string);
+const summary = await agent.ask("Summarize this data concisely:\\n" + data);
+await tools.write("summary.md", summary);
+await ctx.done({ summaryLength: summary.length });
+
+// Example C: Complex (autoresearch loop)
+import { ctx, agent, tools } from "@trama-dev/runtime";
+
+let code = (ctx.state.code as string | undefined) ?? await tools.read("target.ts");
+let bestMetric = (ctx.state.bestMetric as number | undefined) ?? Infinity;
+
+for (let i = ctx.iteration; i < ctx.maxIterations; i++) {
+  const proposal = await agent.generate<{ reasoning: string; newCode: string }>({
+    prompt: "Analyze this code and propose ONE specific improvement:\\n" + code,
+    schema: { reasoning: "string: why this change helps", newCode: "string: complete improved code" },
+  });
+
+  await tools.write("candidate.ts", proposal.newCode);
+  const bench = await tools.shell("npx tsx benchmark.ts candidate.ts");
+
+  if (bench.exitCode !== 0) {
+    await ctx.log("benchmark failed", { stderr: bench.stderr });
+    continue;
+  }
+
+  const metric = parseFloat(bench.stdout.trim());
+  if (metric < bestMetric) {
+    code = proposal.newCode;
+    bestMetric = metric;
+    await ctx.log("improved", { iteration: i, metric, reasoning: proposal.reasoning });
+    ctx.state = { code, bestMetric };
+    await ctx.checkpoint();
+  }
+}
+
+await tools.write("target.ts", code);
+await ctx.done({ finalMetric: bestMetric });`;
+function getSystemPrompt() {
+    return (`You are generating a TypeScript program for the trama runtime.\n\n` +
+        `Runtime API:\n${RUNTIME_TYPES}\n\n` +
+        `Examples:\n${EXAMPLE_PROGRAMS}`);
+}
+function projectsDir() {
+    return join(homedir(), ".trama", "projects");
+}
+export function validateProjectName(name) {
+    if (!name || /[\/\\]/.test(name) || name === "." || name === "..") {
+        throw new Error(`Invalid project name: "${name}". Must be a simple directory name without path separators.`);
+    }
+}
+function resolveProject(name) {
+    validateProjectName(name);
+    const dir = join(projectsDir(), name);
+    if (!existsSync(dir)) {
+        throw new Error(`Project "${name}" not found. Run \`trama list\` to see available projects.`);
+    }
+    return dir;
+}
+// --- Public API ---
+export async function createProject(name, prompt, options) {
+    validateProjectName(name);
+    const projectDir = join(projectsDir(), name);
+    let keepProjectOnFailure = false;
+    if (existsSync(projectDir)) {
+        throw new Error(`Project "${name}" already exists.`);
+    }
+    mkdirSync(projectDir, { recursive: true });
+    try {
+        mkdirSync(join(projectDir, "history"), { recursive: true });
+        mkdirSync(join(projectDir, "logs"), { recursive: true });
+        writeFileSync(join(projectDir, "package.json"), JSON.stringify({ type: "module" }, null, 2));
+        writeFileSync(join(projectDir, ".gitignore"), "node_modules/\nstate.json\nlogs/\nhistory/\n");
+        const meta = {
+            input: { prompt, args: {} },
+            createdAt: new Date().toISOString(),
+            piVersion: PI_VERSION,
+        };
+        writeFileSync(join(projectDir, "meta.json"), JSON.stringify(meta, null, 2));
+        const config = loadConfig();
+        if (options?.model)
+            config.model = options.model;
+        const adapter = new PiAdapter(config, projectDir);
+        console.log(`Generating program for "${name}"...`);
+        const program = await adapter.ask(`${prompt}\n\nOutput ONLY the TypeScript program. No markdown fences. No explanation.`, { system: getSystemPrompt() });
+        writeFileSync(join(projectDir, "program.ts"), program);
+        keepProjectOnFailure = true;
+        console.log("Validating program...");
+        await smokeRunAndRepair(projectDir, adapter, "create");
+        copyFileSync(join(projectDir, "program.ts"), join(projectDir, "history", "0001.ts"));
+        appendFileSync(join(projectDir, "history", "index.jsonl"), JSON.stringify({ version: 1, reason: "create", timestamp: new Date().toISOString(), prompt }) + "\n");
+        console.log(`Created ${name}. Run with: trama run ${name}`);
+    }
+    catch (err) {
+        if (!keepProjectOnFailure) {
+            rmSync(projectDir, { recursive: true, force: true });
+        }
+        throw err;
+    }
+}
+export async function updateProject(name, prompt) {
+    const projectDir = resolveProject(name);
+    const programPath = join(projectDir, "program.ts");
+    const originalSource = readFileSync(programPath, "utf-8");
+    const state = loadState(projectDir);
+    const meta = JSON.parse(readFileSync(join(projectDir, "meta.json"), "utf-8"));
+    const historyIndexPath = join(projectDir, "history", "index.jsonl");
+    const originalHistory = existsSync(historyIndexPath) ? readFileSync(historyIndexPath, "utf-8") : "";
+    const config = loadConfig();
+    const adapter = new PiAdapter(config, projectDir);
+    const systemPrompt = getSystemPrompt() +
+        `\n\nOriginal prompt: ${meta.input.prompt}` +
+        `\n\nCurrent program.ts:\n${originalSource}` +
+        (Object.keys(state).length > 0 ? `\n\nCurrent state:\n${JSON.stringify(state, null, 2)}` : "");
+    console.log(`Updating "${name}"...`);
+    const updated = await adapter.ask(`${prompt}\n\nOutput the complete updated program.ts. No partial patches. No markdown fences. No explanation.`, { system: systemPrompt });
+    const backupRoot = mkdtempSync(join(tmpdir(), "trama-update-backup-"));
+    const backupDir = join(backupRoot, "project");
+    cpSync(projectDir, backupDir, { recursive: true });
+    writeFileSync(programPath, updated);
+    console.log("Validating updated program...");
+    try {
+        await smokeRunAndRepair(projectDir, adapter, "update");
+    }
+    catch (err) {
+        const failedHistory = existsSync(historyIndexPath) ? readFileSync(historyIndexPath, "utf-8") : "";
+        rmSync(projectDir, { recursive: true, force: true });
+        cpSync(backupDir, projectDir, { recursive: true });
+        if (failedHistory.startsWith(originalHistory)) {
+            const repairEntries = failedHistory.slice(originalHistory.length);
+            if (repairEntries.length > 0) {
+                appendFileSync(join(projectDir, "history", "index.jsonl"), repairEntries);
+            }
+        }
+        rmSync(backupRoot, { recursive: true, force: true });
+        throw new Error(`Update validation failed — project files have been restored to the previous version.\n` +
+            `${err instanceof Error ? err.message : err}`);
+    }
+    rmSync(backupRoot, { recursive: true, force: true });
+    copyToHistory(projectDir, "update", prompt);
+    console.log(`Updated ${name}. Run with: trama run ${name}`);
+}
+export async function listProjects() {
+    const dir = projectsDir();
+    if (!existsSync(dir)) {
+        console.log("No projects found.");
+        return;
+    }
+    const entries = readdirSync(dir, { withFileTypes: true })
+        .filter(e => e.isDirectory());
+    if (entries.length === 0) {
+        console.log("No projects found.");
+        return;
+    }
+    for (const entry of entries) {
+        const projectDir = join(dir, entry.name);
+        let prompt = "";
+        let modified = "";
+        try {
+            const meta = JSON.parse(readFileSync(join(projectDir, "meta.json"), "utf-8"));
+            prompt = meta.input?.prompt ?? "";
+            if (prompt.length > 60)
+                prompt = prompt.slice(0, 57) + "...";
+        }
+        catch { /* no meta */ }
+        try {
+            const stat = statSync(join(projectDir, "program.ts"));
+            modified = stat.mtime.toISOString().slice(0, 19).replace("T", " ");
+        }
+        catch { /* no program.ts */ }
+        console.log(`  ${entry.name}  ${prompt}  ${modified}`);
+    }
+}
+export async function showLogs(name) {
+    const projectDir = resolveProject(name);
+    const logsPath = join(projectDir, "logs", "latest.jsonl");
+    if (!existsSync(logsPath)) {
+        console.log("No logs found.");
+        return;
+    }
+    const content = readFileSync(logsPath, "utf-8").trim();
+    if (!content) {
+        console.log("No log entries.");
+        return;
+    }
+    for (const line of content.split("\n")) {
+        try {
+            const entry = JSON.parse(line);
+            const time = new Date(entry.ts).toISOString().slice(11, 19);
+            const data = entry.data ? `  ${JSON.stringify(entry.data)}` : "";
+            console.log(`[${time}] ${entry.message}${data}`);
+        }
+        catch {
+            console.log(line);
+        }
+    }
+}

package/dist/pi-adapter.d.ts

@@ -0,0 +1,12 @@
+import type { PiAdapterConfig, RepairInput } from "./types.js";
+export declare class PiAdapter {
+    private config;
+    private cwd;
+    constructor(config: PiAdapterConfig, cwd: string);
+    private createSession;
+    private extractText;
+    ask(prompt: string, options?: {
+        system?: string;
+    }): Promise<string>;
+    repair(input: RepairInput): Promise<string>;
+}

package/dist/pi-adapter.js

@@ -0,0 +1,59 @@
+import { createAgentSession, SessionManager, DefaultResourceLoader, } from "@mariozechner/pi-coding-agent";
+import { getModel } from "@mariozechner/pi-ai";
+export class PiAdapter {
+    config;
+    cwd;
+    constructor(config, cwd) {
+        this.config = config;
+        this.cwd = cwd;
+    }
+    async createSession(systemPrompt) {
+        const resourceLoader = new DefaultResourceLoader({
+            cwd: this.cwd,
+            noExtensions: true,
+            noSkills: true,
+            ...(systemPrompt && { appendSystemPrompt: systemPrompt }),
+        });
+        await resourceLoader.reload();
+        const { session } = await createAgentSession({
+            cwd: this.cwd,
+            model: getModel(this.config.provider, this.config.model),
+            sessionManager: SessionManager.inMemory(),
+            resourceLoader,
+        });
+        return session;
+    }
+    extractText(session) {
+        const messages = session.state.messages;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const msg = messages[i];
+            if ("role" in msg && msg.role === "assistant") {
+                return msg.content
+                    .filter(b => b.type === "text" && b.text)
+                    .map(b => b.text)
+                    .join("");
+            }
+        }
+        return "";
+    }
+    async ask(prompt, options) {
+        const session = await this.createSession(options?.system);
+        try {
+            await session.prompt(prompt);
+            const text = this.extractText(session);
+            if (!text)
+                throw new Error("Empty response from LLM");
+            return text;
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    async repair(input) {
+        return this.ask(`Fix this program so it runs.\n\n` +
+            `Runtime types:\n${input.runtimeTypes}\n\n` +
+            `Broken program:\n${input.programSource}\n\n` +
+            `Error:\n${input.error}\n\n` +
+            `Output ONLY the fixed program. No explanation.`, { system: "You are a TypeScript repair tool." });
+    }
+}

package/dist/runner.d.ts

@@ -0,0 +1,15 @@
+import type { RunOptions, TramaConfig } from "./types.js";
+import { PiAdapter } from "./pi-adapter.js";
+export declare const PI_VERSION: string;
+export declare const RUNTIME_TYPES = "// @trama-dev/runtime - Complete API\n\nexport interface Ctx {\n  input: { prompt: string; args: Record<string, unknown> };\n  state: Record<string, unknown>;\n  iteration: number;\n  maxIterations: number;\n  log(message: string, data?: Record<string, unknown>): Promise<void>;\n  checkpoint(): Promise<void>;\n  done(result?: Record<string, unknown>): Promise<void>;\n}\n\nexport interface Agent {\n  ask(prompt: string, options?: { system?: string }): Promise<string>;\n  generate<T>(input: {\n    prompt: string;\n    schema: Record<string, string>;\n    system?: string;\n  }): Promise<T>;\n}\n\nexport interface ShellResult {\n  exitCode: number;\n  stdout: string;\n  stderr: string;\n}\n\nexport interface Tools {\n  read(path: string): Promise<string>;\n  write(path: string, content: string): Promise<void>;\n  shell(command: string, options?: { cwd?: string; timeout?: number }): Promise<ShellResult>;\n  fetch(url: string, options?: {\n    method?: string;\n    headers?: Record<string, string>;\n    body?: string;\n  }): Promise<{ status: number; body: string; headers: Record<string, string> }>;\n}\n\nexport declare const ctx: Ctx;\nexport declare const agent: Agent;\nexport declare const tools: Tools;";
+export declare function loadConfig(): TramaConfig;
+export declare function loadState(projectDir: string): Record<string, unknown>;
+/**
+ * Copy current program.ts to history/NNNN.ts and append to index.jsonl.
+ *
+ * WARNING: Do NOT use this for create-time repair attempts.
+ * Create-time repairs go to index.jsonl only (reason: "create-repair").
+ */
+export declare function copyToHistory(projectDir: string, reason: string, detail?: string): void;
+export declare function smokeRunAndRepair(projectDir: string, adapter: PiAdapter, reason: "create" | "update"): Promise<void>;
+export declare function runProgram(options: RunOptions): Promise<void>;

package/dist/runner.js

@@ -0,0 +1,470 @@
+import { createServer } from "http";
+import { spawn } from "child_process";
+import { readFileSync, writeFileSync, appendFileSync, readdirSync, copyFileSync, mkdirSync, existsSync, symlinkSync, rmSync, lstatSync, readlinkSync, } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+import { PiAdapter } from "./pi-adapter.js";
+import { createContext } from "./context.js";
+import { createAgent } from "./agent.js";
+import { createTools } from "./tools.js";
+// --- Module resolution for child processes ---
+/**
+ * Find the node_modules directory that contains @trama-dev/runtime.
+ * Works for both global install and monorepo development.
+ */
+function findRuntimeNodeModules() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    while (dir !== dirname(dir)) {
+        const candidate = join(dir, "node_modules");
+        if (existsSync(join(candidate, "@trama-dev", "runtime"))) {
+            return candidate;
+        }
+        dir = dirname(dir);
+    }
+    throw new Error("Could not locate node_modules containing @trama-dev/runtime");
+}
+const TRAMA_NODE_MODULES = findRuntimeNodeModules();
+const TSX_CLI = join(TRAMA_NODE_MODULES, "tsx", "dist", "cli.mjs");
+export const PI_VERSION = JSON.parse(readFileSync(join(TRAMA_NODE_MODULES, "@mariozechner", "pi-coding-agent", "package.json"), "utf-8")).version;
+/**
+ * Ensure the project directory has a node_modules symlink to @trama-dev/runtime.
+ * Only replaces the path if it is a symlink (ours) or doesn't exist.
+ * Refuses to touch a real directory to avoid destroying user content.
+ */
+function ensureRuntimeLink(projectDir) {
+    const linkDir = join(projectDir, "node_modules", "@trama-dev");
+    const linkPath = join(linkDir, "runtime");
+    const target = join(TRAMA_NODE_MODULES, "@trama-dev", "runtime");
+    try {
+        const stat = lstatSync(linkPath);
+        if (stat.isSymbolicLink()) {
+            // Ours — check if already correct
+            if (readlinkSync(linkPath) === target)
+                return;
+            rmSync(linkPath);
+        }
+        else {
+            // Real directory/file — not ours, refuse to destroy it
+            throw new Error(`${linkPath} exists and is not a symlink. ` +
+                `trama needs this path for module resolution. ` +
+                `Remove it manually or rename it to proceed.`);
+        }
+    }
+    catch (err) {
+        // Re-throw if it's our own error (not ENOENT)
+        if (err instanceof Error && !("code" in err))
+            throw err;
+        // ENOENT — path doesn't exist, proceed to create
+    }
+    mkdirSync(linkDir, { recursive: true });
+    symlinkSync(target, linkPath, "dir");
+}
+/**
+ * Ensure project has ESM package.json and .gitignore.
+ * If package.json exists but lacks "type": "module", patches it in.
+ */
+function ensureProjectScaffold(projectDir) {
+    const pkgPath = join(projectDir, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            if (pkg.type !== "module") {
+                pkg.type = "module";
+                writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+            }
+        }
+        catch (err) {
+            throw new Error(`Malformed package.json at ${pkgPath}. ` +
+                `trama will not overwrite it automatically; fix or remove it and try again.\n` +
+                `Parse error: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    else {
+        writeFileSync(pkgPath, JSON.stringify({ type: "module" }, null, 2));
+    }
+    const giPath = join(projectDir, ".gitignore");
+    const requiredEntries = ["node_modules/", "state.json", "logs/", "history/"];
+    if (existsSync(giPath)) {
+        const existing = readFileSync(giPath, "utf-8");
+        const missing = requiredEntries.filter(e => !existing.split("\n").some(line => line.trim() === e));
+        if (missing.length > 0) {
+            const suffix = existing.endsWith("\n") ? "" : "\n";
+            writeFileSync(giPath, existing + suffix + missing.join("\n") + "\n");
+        }
+    }
+    else {
+        writeFileSync(giPath, requiredEntries.join("\n") + "\n");
+    }
+}
+// --- Runtime type definitions (included in system prompts) ---
+export const RUNTIME_TYPES = `// @trama-dev/runtime - Complete API
+
+export interface Ctx {
+  input: { prompt: string; args: Record<string, unknown> };
+  state: Record<string, unknown>;
+  iteration: number;
+  maxIterations: number;
+  log(message: string, data?: Record<string, unknown>): Promise<void>;
+  checkpoint(): Promise<void>;
+  done(result?: Record<string, unknown>): Promise<void>;
+}
+
+export interface Agent {
+  ask(prompt: string, options?: { system?: string }): Promise<string>;
+  generate<T>(input: {
+    prompt: string;
+    schema: Record<string, string>;
+    system?: string;
+  }): Promise<T>;
+}
+
+export interface ShellResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface Tools {
+  read(path: string): Promise<string>;
+  write(path: string, content: string): Promise<void>;
+  shell(command: string, options?: { cwd?: string; timeout?: number }): Promise<ShellResult>;
+  fetch(url: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  }): Promise<{ status: number; body: string; headers: Record<string, string> }>;
+}
+
+export declare const ctx: Ctx;
+export declare const agent: Agent;
+export declare const tools: Tools;`;
+// --- Config & state loaders ---
+export function loadConfig() {
+    const configPath = join(homedir(), ".trama", "config.json");
+    const defaults = {
+        provider: "anthropic",
+        model: "claude-sonnet-4-20250514",
+        maxRepairAttempts: 3,
+        defaultTimeout: 300_000,
+        defaultMaxIterations: 100,
+    };
+    try {
+        return { ...defaults, ...JSON.parse(readFileSync(configPath, "utf-8")) };
+    }
+    catch {
+        return defaults;
+    }
+}
+export function loadState(projectDir) {
+    const statePath = join(projectDir, "state.json");
+    if (!existsSync(statePath))
+        return {};
+    const raw = readFileSync(statePath, "utf-8");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Corrupt state.json in ${projectDir} — cannot safely continue.\n` +
+            `Parse error: ${err instanceof Error ? err.message : err}\n` +
+            `Back up or delete state.json to reset state.`);
+    }
+}
+// --- IPC Server ---
+function createIPCServer(ctx, agentImpl, toolsImpl) {
+    return createServer((req, res) => {
+        if (req.method !== "POST") {
+            res.writeHead(405);
+            res.end("Method not allowed");
+            return;
+        }
+        let body = "";
+        req.on("data", (chunk) => { body += chunk; });
+        req.on("end", async () => {
+            try {
+                const data = JSON.parse(body);
+                let result;
+                switch (req.url) {
+                    case "/agent/ask":
+                        result = await agentImpl.ask(data.prompt, { system: data.system });
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ result }));
+                        break;
+                    case "/agent/generate":
+                        result = await agentImpl.generate(data);
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ result }));
+                        break;
+                    case "/tools/read":
+                        result = await toolsImpl.read(data.path);
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ result }));
+                        break;
+                    case "/tools/write":
+                        await toolsImpl.write(data.path, data.content);
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ result: null }));
+                        break;
+                    case "/tools/shell":
+                        result = await toolsImpl.shell(data.command, { cwd: data.cwd, timeout: data.timeout });
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify(result));
+                        break;
+                    case "/tools/fetch":
+                        result = await toolsImpl.fetch(data.url, {
+                            method: data.method, headers: data.headers, body: data.body,
+                        });
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify(result));
+                        break;
+                    case "/ctx/checkpoint":
+                        ctx.state = data.state;
+                        await ctx.checkpoint();
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ result: null }));
+                        break;
+                    case "/ctx/log":
+                        await ctx.log(data.message, data.data);
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ result: null }));
+                        break;
+                    case "/ctx/done":
+                        ctx.state = data.state;
+                        await ctx.done(data.result);
+                        res.writeHead(200, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ result: null }));
+                        break;
+                    default:
+                        res.writeHead(404);
+                        res.end("Not found");
+                }
+            }
+            catch (err) {
+                res.writeHead(500);
+                res.end(String(err));
+            }
+        });
+    });
+}
+function startServer(server) {
+    return new Promise((resolve, reject) => {
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (addr && typeof addr === "object") {
+                resolve(addr.port);
+            }
+            else {
+                reject(new Error("Failed to get server port"));
+            }
+        });
+        server.on("error", reject);
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close(err => (err ? reject(err) : resolve()));
+    });
+}
+/** Kill orphan shell processes, drop all HTTP connections, then close. */
+function forceCloseServer(server, toolsImpl) {
+    toolsImpl.killActiveShells();
+    server.closeAllConnections();
+    return closeServer(server);
+}
+// --- Child process management ---
+/**
+ * Collect stdout/stderr as strings and wait for exit.
+ * Enforces wall-clock timeout via explicit setTimeout + kill.
+ */
+function waitForChild(child, timeout, sinks) {
+    return new Promise((resolve, reject) => {
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let exited = false;
+        child.stdout?.on("data", (chunk) => {
+            const text = chunk.toString();
+            stdout += text;
+            sinks?.stdout?.(text);
+        });
+        child.stderr?.on("data", (chunk) => {
+            const text = chunk.toString();
+            stderr += text;
+            sinks?.stderr?.(text);
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!exited)
+                    child.kill("SIGKILL");
+            }, 5000);
+        }, timeout);
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            exited = true;
+            clearTimeout(timer);
+            if (timedOut) {
+                resolve({ exitCode: 1, stdout, stderr: stderr + "\n[trama] program killed: timeout" });
+            }
+            else {
+                resolve({ exitCode: code ?? 1, stdout, stderr });
+            }
+        });
+    });
+}
+// --- History management ---
+/**
+ * Copy current program.ts to history/NNNN.ts and append to index.jsonl.
+ *
+ * WARNING: Do NOT use this for create-time repair attempts.
+ * Create-time repairs go to index.jsonl only (reason: "create-repair").
+ */
+export function copyToHistory(projectDir, reason, detail) {
+    const historyDir = join(projectDir, "history");
+    const existing = readdirSync(historyDir).filter(f => /^\d{4}\.ts$/.test(f));
+    const nums = existing.map(f => parseInt(f.replace(".ts", ""), 10));
+    const nextNum = nums.length > 0 ? Math.max(...nums) + 1 : 1;
+    const next = String(nextNum).padStart(4, "0");
+    copyFileSync(join(projectDir, "program.ts"), join(historyDir, `${next}.ts`));
+    const entry = { version: nextNum, reason, timestamp: new Date().toISOString() };
+    if (reason === "repair" && detail)
+        entry.error = detail;
+    if (reason === "update" && detail)
+        entry.prompt = detail;
+    appendFileSync(join(historyDir, "index.jsonl"), JSON.stringify(entry) + "\n");
+}
+// --- Smoke run (used by create and update) ---
+export async function smokeRunAndRepair(projectDir, adapter, reason) {
+    mkdirSync(join(projectDir, "history"), { recursive: true });
+    mkdirSync(join(projectDir, "logs"), { recursive: true });
+    ensureProjectScaffold(projectDir);
+    ensureRuntimeLink(projectDir);
+    const maxAttempts = 3;
+    for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+        const ctx = createContext(projectDir, loadState(projectDir));
+        const agentImpl = createAgent(adapter);
+        const toolsImpl = createTools(projectDir);
+        writeFileSync(join(projectDir, "logs", "latest.jsonl"), "");
+        const server = createIPCServer(ctx, agentImpl, toolsImpl);
+        const port = await startServer(server);
+        try {
+            const meta = JSON.parse(readFileSync(join(projectDir, "meta.json"), "utf-8"));
+            const child = spawn(process.execPath, [TSX_CLI, join(projectDir, "program.ts")], {
+                cwd: projectDir,
+                env: {
+                    ...process.env,
+                    TRAMA_PORT: String(port),
+                    TRAMA_INPUT: JSON.stringify(meta.input),
+                    TRAMA_STATE: JSON.stringify(ctx.state),
+                    TRAMA_ITERATION: String(ctx.iteration),
+                    TRAMA_MAX_ITERATIONS: String(ctx.maxIterations),
+                },
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            const result = await waitForChild(child, 5000, {
+                stdout: chunk => { process.stdout.write(chunk); },
+            });
+            if (result.exitCode === 0) {
+                await closeServer(server);
+                return;
+            }
+            throw new Error(`Smoke run failed (exit ${result.exitCode})\nstdout: ${result.stdout}\nstderr: ${result.stderr}`);
+        }
+        catch (error) {
+            if (attempt === maxAttempts) {
+                await forceCloseServer(server, toolsImpl);
+                throw new Error(`Smoke run failed after ${maxAttempts} repair attempts: ${error}`);
+            }
+            appendFileSync(join(projectDir, "history", "index.jsonl"), JSON.stringify({
+                reason: `${reason}-repair`,
+                timestamp: new Date().toISOString(),
+                error: String(error),
+            }) + "\n");
+            const source = readFileSync(join(projectDir, "program.ts"), "utf-8");
+            const fixed = await adapter.repair({
+                programSource: source,
+                error: String(error),
+                runtimeTypes: RUNTIME_TYPES,
+            });
+            writeFileSync(join(projectDir, "program.ts"), fixed);
+            await forceCloseServer(server, toolsImpl);
+        }
+    }
+}
+// --- Core execution ---
+export async function runProgram(options) {
+    const { projectDir } = options;
+    if (!existsSync(join(projectDir, "meta.json"))) {
+        throw new Error(`Project not found at ${projectDir}. ` +
+            `Run \`trama list\` to see available projects.`);
+    }
+    const config = loadConfig();
+    const maxRepairAttempts = options.maxRepairAttempts ?? config.maxRepairAttempts;
+    const timeout = options.timeout ?? config.defaultTimeout;
+    const maxIterations = config.defaultMaxIterations;
+    if (!Number.isFinite(timeout) || timeout <= 0) {
+        throw new Error(`Invalid timeout: ${timeout}. Must be a positive number.`);
+    }
+    if (!Number.isInteger(maxRepairAttempts) || maxRepairAttempts < 0) {
+        throw new Error(`Invalid maxRepairAttempts: ${maxRepairAttempts}. Must be a non-negative integer.`);
+    }
+    mkdirSync(join(projectDir, "history"), { recursive: true });
+    mkdirSync(join(projectDir, "logs"), { recursive: true });
+    ensureProjectScaffold(projectDir);
+    ensureRuntimeLink(projectDir);
+    const adapter = new PiAdapter(config, projectDir);
+    for (let attempt = 0; attempt <= maxRepairAttempts; attempt++) {
+        const ctx = createContext(projectDir, loadState(projectDir), { maxIterations });
+        const agentImpl = createAgent(adapter);
+        const toolsImpl = createTools(projectDir);
+        const logsPath = join(projectDir, "logs", "latest.jsonl");
+        writeFileSync(logsPath, "");
+        const server = createIPCServer(ctx, agentImpl, toolsImpl);
+        const port = await startServer(server);
+        try {
+            const meta = JSON.parse(readFileSync(join(projectDir, "meta.json"), "utf-8"));
+            const child = spawn(process.execPath, [TSX_CLI, join(projectDir, "program.ts")], {
+                cwd: projectDir,
+                env: {
+                    ...process.env,
+                    TRAMA_PORT: String(port),
+                    TRAMA_INPUT: JSON.stringify(meta.input),
+                    TRAMA_STATE: JSON.stringify(ctx.state),
+                    TRAMA_ITERATION: String(ctx.iteration),
+                    TRAMA_MAX_ITERATIONS: String(ctx.maxIterations),
+                },
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            const result = await waitForChild(child, timeout, {
+                stdout: chunk => { process.stdout.write(chunk); },
+            });
+            if (result.exitCode === 0) {
+                await closeServer(server);
+                return;
+            }
+            throw new Error(`program.ts exited with code ${result.exitCode}\n` +
+                `stdout: ${result.stdout}\n` +
+                `stderr: ${result.stderr}`);
+        }
+        catch (error) {
+            if (attempt === maxRepairAttempts) {
+                await forceCloseServer(server, toolsImpl);
+                throw new Error(`Failed after ${maxRepairAttempts} repair attempts: ${error}`);
+            }
+            await ctx.log(`Repair attempt ${attempt + 1}/${maxRepairAttempts}`, { error: String(error) });
+            const source = readFileSync(join(projectDir, "program.ts"), "utf-8");
+            const fixed = await adapter.repair({
+                programSource: source,
+                error: String(error),
+                runtimeTypes: RUNTIME_TYPES,
+            });
+            writeFileSync(join(projectDir, "program.ts"), fixed);
+            copyToHistory(projectDir, "repair", String(error));
+            await forceCloseServer(server, toolsImpl);
+        }
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,6 @@
+import type { Tools } from "./types.js";
+export interface ToolsWithCleanup extends Tools {
+    /** Kill all in-flight shell processes. Called by runner on timeout/error. */
+    killActiveShells(): void;
+}
+export declare function createTools(projectDir: string): ToolsWithCleanup;

package/dist/tools.js

@@ -0,0 +1,84 @@
+import { spawn } from "child_process";
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { resolve, dirname, sep } from "path";
+export function createTools(projectDir) {
+    const normalizedProjectDir = resolve(projectDir);
+    const activeShells = new Set();
+    /**
+     * Path traversal guard. Not a security sandbox — just a footgun guard.
+     * Uses normalizedProjectDir + sep to prevent /tmp/foo-bar matching /tmp/foo.
+     */
+    const resolvePath = (p) => {
+        const resolved = resolve(normalizedProjectDir, p);
+        if (resolved !== normalizedProjectDir && !resolved.startsWith(normalizedProjectDir + sep)) {
+            throw new Error(`Path escapes project directory: ${p}`);
+        }
+        return resolved;
+    };
+    return {
+        killActiveShells() {
+            for (const proc of activeShells) {
+                proc.kill("SIGKILL");
+            }
+            activeShells.clear();
+        },
+        async read(path) {
+            return readFileSync(resolvePath(path), "utf-8");
+        },
+        async write(path, content) {
+            const target = resolvePath(path);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, content);
+        },
+        async shell(command, options = {}) {
+            const timeout = options.timeout ?? 30_000;
+            const cwd = options.cwd ? resolvePath(options.cwd) : normalizedProjectDir;
+            return new Promise((resolve) => {
+                const child = spawn("sh", ["-c", command], {
+                    cwd,
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
+                activeShells.add(child);
+                let stdout = "";
+                let stderr = "";
+                let timedOut = false;
+                let exited = false;
+                child.stdout.on("data", (chunk) => { stdout += chunk; });
+                child.stderr.on("data", (chunk) => { stderr += chunk; });
+                child.on("error", (err) => {
+                    activeShells.delete(child);
+                    resolve({ exitCode: 1, stdout, stderr: err.message });
+                });
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    child.kill("SIGTERM");
+                    setTimeout(() => {
+                        if (!exited)
+                            child.kill("SIGKILL");
+                    }, 5000);
+                }, timeout);
+                child.on("close", (code) => {
+                    exited = true;
+                    activeShells.delete(child);
+                    clearTimeout(timer);
+                    resolve({
+                        exitCode: timedOut ? 1 : (code ?? 1),
+                        stdout,
+                        stderr: timedOut ? stderr + "\ntimeout" : stderr,
+                    });
+                });
+            });
+        },
+        async fetch(url, options = {}) {
+            const response = await globalThis.fetch(url, {
+                method: options.method ?? "GET",
+                headers: options.headers,
+                body: options.body,
+            });
+            const body = await response.text();
+            const headers = {};
+            response.headers.forEach((v, k) => { headers[k] = v; });
+            return { status: response.status, body, headers };
+        }
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+export interface Ctx {
+    /** Original user prompt and any arguments */
+    input: {
+        prompt: string;
+        args: Record<string, unknown>;
+    };
+    /**
+     * Persistent state. Must be strictly JSON-serializable.
+     * Local working copy — only checkpoint() and done() persist to disk.
+     * Reserved keys: any key starting with `__trama_` is reserved.
+     */
+    state: Record<string, unknown>;
+    /**
+     * Current iteration counter (starts at 0).
+     * Advances only when checkpoint() or done() is called.
+     */
+    iteration: number;
+    /** Max iterations hint. Not enforced by runtime. */
+    maxIterations: number;
+    /** Write a structured log entry */
+    log(message: string, data?: Record<string, unknown>): Promise<void>;
+    /** Persist current ctx.state to disk */
+    checkpoint(): Promise<void>;
+    /**
+     * Signal program completion. Persists state and logs result.
+     * Does NOT terminate execution — program should return naturally.
+     * Idempotent: second call is a no-op.
+     */
+    done(result?: Record<string, unknown>): Promise<void>;
+}
+export interface Agent {
+    /**
+     * LLM call via pi-coding-agent. Returns plain text.
+     * The underlying pi agent may use its built-in tools autonomously.
+     */
+    ask(prompt: string, options?: {
+        system?: string;
+    }): Promise<string>;
+    /**
+     * Structured LLM call. Returns typed object matching the provided schema.
+     * Supported schema value prefixes: "string", "number", "boolean".
+     * Retries once on parse/validation failure.
+     */
+    generate<T>(input: {
+        prompt: string;
+        schema: Record<string, string>;
+        system?: string;
+    }): Promise<T>;
+}
+export interface ShellResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface Tools {
+    /** Read a file. Path is relative to project dir. */
+    read(path: string): Promise<string>;
+    /** Write a file. Path is relative to project dir. */
+    write(path: string, content: string): Promise<void>;
+    /** Execute a shell command. Returns structured result. */
+    shell(command: string, options?: {
+        cwd?: string;
+        timeout?: number;
+    }): Promise<ShellResult>;
+    /** HTTP fetch. Returns response body as string. */
+    fetch(url: string, options?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
+    }): Promise<{
+        status: number;
+        body: string;
+        headers: Record<string, string>;
+    }>;
+}
+export interface PiAdapterConfig {
+    provider: string;
+    model: string;
+}
+export interface RunOptions {
+    projectDir: string;
+    maxRepairAttempts?: number;
+    timeout?: number;
+}
+export interface RepairInput {
+    programSource: string;
+    error: string;
+    runtimeTypes: string;
+}
+export interface ChildResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface TramaConfig extends PiAdapterConfig {
+    maxRepairAttempts: number;
+    defaultTimeout: number;
+    defaultMaxIterations: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// @trama-dev/runtime - All shared types
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@trama-dev/runtime",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./runner": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Runtime and client library for trama — an agentic runtime for agent-authored TypeScript programs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NaNhkNaN/trama.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/NaNhkNaN/trama",
+  "bugs": "https://github.com/NaNhkNaN/trama/issues",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "0.63.1",
+    "@mariozechner/pi-ai": "0.63.1",
+    "tsx": "^4.0.0"
+  }
+}