@trama-dev/session 0.1.5

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,41 @@
+# @trama-dev/session
+
+> Multi-agent coordination for trama programs.
+
+The session layer for [trama](https://github.com/NaNhkNaN/trama) — shared workspace, cooperative suspension, and structured program results for coordinating multiple agent-authored programs.
+
+## Usage
+
+```typescript
+import { ctx, agent, tools, workspace } from "@trama-dev/runtime";
+import { Session } from "@trama-dev/session";
+
+const session = await Session.createTemp();
+
+// Spawn participants — each is a full trama program
+const handle = session.spawn("check-sql", {
+  projectDir: "~/.trama/projects/check-sql",
+});
+
+const result = await handle.wait();
+// { status: "done" | "yielded" | "failed", reason?, result? }
+
+// Resume a yielded participant
+if (result.status === "yielded") {
+  const resumed = await handle.resume({ feedback: "approved" });
+  await resumed.wait();
+}
+```
+
+## What the session layer provides
+
+- **Shared workspace** — participants read and write artifacts through a common directory with atomic writes and path guarding.
+- **Structured results** — `ProgramResult` with `status`, `reason`, and `result` fields. The session layer never reads `state.json` directly.
+- **Yield/resume** — participants can suspend cooperatively via `ctx.yield()` and be resumed with new args.
+- **Failure isolation** — each participant has its own trama lifecycle, repair loop, and state. A crashing participant doesn't corrupt the workspace or block others.
+
+## Design
+
+The session layer is **policy**. The runtime is **mechanism**. The session manages coordination (who participates, when to resume). The runtime manages execution (state persistence, auto-repair, version history). This boundary is enforced: `session` depends on `runtime`, never the reverse.
+
+See the [main README](https://github.com/NaNhkNaN/trama) for the full API reference, and [docs/workspace-rfc.md](https://github.com/NaNhkNaN/trama/blob/main/docs/workspace-rfc.md) for the design rationale.

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+import type { ProgramResult } from "@trama-dev/runtime/runner";
+export type { ProgramResult };
+export interface SessionOptions {
+    /** Directory for shared workspace artifacts. Created if it doesn't exist. */
+    workspace: string;
+}
+export interface SpawnOptions {
+    /** Path to the trama project directory. */
+    projectDir: string;
+    /** Arguments passed to the program via ctx.input.args. */
+    args?: Record<string, unknown>;
+    /** Per-phase timeout in ms. */
+    timeout?: number;
+    /** Max repair attempts. */
+    maxRepairAttempts?: number;
+}
+export interface ParticipantHandle {
+    /** The participant name. */
+    name: string;
+    /** Wait for participant to complete, yield, or fail. */
+    wait(): Promise<ProgramResult>;
+    /**
+     * Resume a yielded participant with optional new args.
+     * Throws if the participant is not in a yielded state.
+     */
+    resume(args?: Record<string, unknown>): Promise<ParticipantHandle>;
+}
+export declare class Session {
+    /** The shared workspace directory path. */
+    readonly workspace: string;
+    private constructor();
+    /**
+     * Create a new session with a shared workspace directory.
+     * The workspace is created if it doesn't exist.
+     */
+    static create(options: SessionOptions): Promise<Session>;
+    /**
+     * Create a new session with a temporary workspace directory.
+     * Useful for testing or ephemeral sessions.
+     */
+    static createTemp(prefix?: string): Promise<Session>;
+    /**
+     * Spawn a trama program as a session participant.
+     * The program gets access to the shared workspace via the workspace API.
+     */
+    spawn(name: string, options: SpawnOptions): ParticipantHandle;
+}

package/dist/index.js

@@ -0,0 +1,87 @@
+import { mkdirSync, existsSync, mkdtempSync } from "fs";
+import { resolve } from "path";
+import { tmpdir } from "os";
+import { runProgram } from "@trama-dev/runtime/runner";
+export class Session {
+    /** The shared workspace directory path. */
+    workspace;
+    constructor(workspace) {
+        this.workspace = workspace;
+    }
+    /**
+     * Create a new session with a shared workspace directory.
+     * The workspace is created if it doesn't exist.
+     */
+    static async create(options) {
+        const workspace = resolve(options.workspace);
+        mkdirSync(workspace, { recursive: true });
+        return new Session(workspace);
+    }
+    /**
+     * Create a new session with a temporary workspace directory.
+     * Useful for testing or ephemeral sessions.
+     */
+    static async createTemp(prefix = "trama-session-") {
+        if (prefix.includes("/") || prefix.includes("\\")) {
+            throw new Error("createTemp prefix must not contain path separators");
+        }
+        const workspace = mkdtempSync(resolve(tmpdir(), prefix));
+        return new Session(workspace);
+    }
+    /**
+     * Spawn a trama program as a session participant.
+     * The program gets access to the shared workspace via the workspace API.
+     */
+    spawn(name, options) {
+        const { projectDir, args, timeout, maxRepairAttempts } = options;
+        const workspaceDir = this.workspace;
+        if (!existsSync(projectDir)) {
+            throw new Error(`Project directory not found: ${projectDir}`);
+        }
+        // Track participant lifecycle state
+        let state = "running";
+        let resultPromise;
+        // Track the latest effective args so multi-yield resumes accumulate state
+        let lastArgs = args;
+        const startRun = (runArgs) => {
+            state = "running";
+            lastArgs = runArgs;
+            const promise = runProgram({
+                projectDir,
+                timeout,
+                maxRepairAttempts,
+                args: runArgs ?? args,
+                workspaceDir,
+            });
+            // Track state transitions when the run completes
+            promise.then((result) => {
+                state = result.status === "yielded" ? "yielded"
+                    : result.status === "done" ? "done"
+                        : "failed";
+            }, () => {
+                // Infrastructure error — treat as failed
+                state = "failed";
+            });
+            return promise;
+        };
+        // Start the run immediately
+        resultPromise = startRun(args);
+        const handle = {
+            name,
+            wait() {
+                return resultPromise;
+            },
+            async resume(newArgs) {
+                // Fail-fast: check current state synchronously — don't block on a running participant
+                if (state !== "yielded") {
+                    throw new Error(`Cannot resume participant "${name}": expected state "yielded" but got "${state}". ` +
+                        `resume() is only valid after a program calls ctx.yield().`);
+                }
+                const mergedArgs = newArgs ? { ...(lastArgs ?? {}), ...newArgs } : lastArgs;
+                resultPromise = startRun(mergedArgs);
+                return handle;
+            },
+        };
+        return handle;
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@trama-dev/session",
+  "version": "0.1.5",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Agent session protocol for trama — multi-agent coordination with shared workspace",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NaNhkNaN/trama.git",
+    "directory": "packages/session"
+  },
+  "homepage": "https://github.com/NaNhkNaN/trama",
+  "bugs": "https://github.com/NaNhkNaN/trama/issues",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "os": ["darwin", "linux"],
+  "dependencies": {
+    "@trama-dev/runtime": "0.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0"
+  }
+}