@trama-dev/session 0.1.5 → 0.2.0

package/README.md

@@ -7,7 +7,7 @@ The session layer for [trama](https://github.com/NaNhkNaN/trama) — shared work
 ## Usage
 
 ```typescript
-import { ctx, agent, tools, workspace } from "@trama-dev/runtime";
+import { ctx } from "@trama-dev/runtime";
 import { Session } from "@trama-dev/session";
 
 const session = await Session.createTemp();
@@ -17,6 +17,10 @@ const handle = session.spawn("check-sql", {
   projectDir: "~/.trama/projects/check-sql",
 });
 
+// Take part in the shared workspace yourself
+await session.workspace.write("diff.txt", diff);
+const findings = await session.workspace.observe("findings/*.json", { expect: 1 });
+
 const result = await handle.wait();
 // { status: "done" | "yielded" | "failed", reason?, result? }
 
@@ -29,7 +33,7 @@ if (result.status === "yielded") {
 
 ## What the session layer provides
 
-- **Shared workspace** — participants read and write artifacts through a common directory with atomic writes and path guarding.
+- **Shared workspace** — participants read and write artifacts through a common directory with atomic writes and path guarding. Participants import it as `workspace` from `@trama-dev/runtime`; the program that created the session uses `session.workspace`.
 - **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.
@@ -38,4 +42,4 @@ if (result.status === "yielded") {
 
 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.
+See the [main README](https://github.com/NaNhkNaN/trama) for the full API reference.

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import type { ProgramResult } from "@trama-dev/runtime/runner";
-export type { ProgramResult };
+import type { ProgramResult, Workspace } from "@trama-dev/runtime/runner";
+export type { ProgramResult, Workspace };
 export interface SessionOptions {
-    /** Directory for shared workspace artifacts. Created if it doesn't exist. */
+    /** Directory for shared workspace artifacts. Created if it doesn't exist. A leading `~` is expanded. */
     workspace: string;
 }
 export interface SpawnOptions {
-    /** Path to the trama project directory. */
+    /** Path to the trama project directory. A leading `~` is expanded. */
     projectDir: string;
     /** Arguments passed to the program via ctx.input.args. */
     args?: Record<string, unknown>;
@@ -26,8 +26,14 @@ export interface ParticipantHandle {
     resume(args?: Record<string, unknown>): Promise<ParticipantHandle>;
 }
 export declare class Session {
-    /** The shared workspace directory path. */
-    readonly workspace: string;
+    /** The shared workspace directory. */
+    readonly workspaceDir: string;
+    /**
+     * The shared workspace itself — the same read / write / list / observe that
+     * participants get as `workspace` from "@trama-dev/runtime". This is how the
+     * program that creates the session takes part in it.
+     */
+    readonly workspace: Workspace;
     private constructor();
     /**
      * Create a new session with a shared workspace directory.

package/dist/index.js

@@ -1,21 +1,34 @@
-import { mkdirSync, existsSync, mkdtempSync } from "fs";
-import { resolve } from "path";
-import { tmpdir } from "os";
-import { runProgram } from "@trama-dev/runtime/runner";
+import { existsSync, mkdtempSync } from "fs";
+import { join, resolve } from "path";
+import { homedir, tmpdir } from "os";
+import { createWorkspace, runProgram } from "@trama-dev/runtime/runner";
+/** Make a path absolute, expanding a leading `~` to the user's home directory. */
+function toAbsolute(path) {
+    if (path === "~")
+        return homedir();
+    if (path.startsWith("~/"))
+        return join(homedir(), path.slice(2));
+    return resolve(path);
+}
 export class Session {
-    /** The shared workspace directory path. */
+    /** The shared workspace directory. */
+    workspaceDir;
+    /**
+     * The shared workspace itself — the same read / write / list / observe that
+     * participants get as `workspace` from "@trama-dev/runtime". This is how the
+     * program that creates the session takes part in it.
+     */
     workspace;
-    constructor(workspace) {
-        this.workspace = workspace;
+    constructor(workspaceDir) {
+        this.workspaceDir = workspaceDir;
+        this.workspace = createWorkspace(workspaceDir);
     }
     /**
      * 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);
+        return new Session(toAbsolute(options.workspace));
     }
     /**
      * Create a new session with a temporary workspace directory.
@@ -25,60 +38,44 @@ export class 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);
+        return new Session(mkdtempSync(resolve(tmpdir(), prefix)));
     }
     /**
      * 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;
+        const { args, timeout, maxRepairAttempts } = options;
+        const projectDir = toAbsolute(options.projectDir);
+        const workspaceDir = this.workspaceDir;
         if (!existsSync(projectDir)) {
             throw new Error(`Project directory not found: ${projectDir}`);
         }
-        // Track participant lifecycle state
+        // Where the participant is in its lifecycle, and the args of its latest run —
+        // a resume merges new args over them, so they accumulate across yields.
         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;
+            const run = runProgram({ projectDir, timeout, maxRepairAttempts, args: runArgs, workspaceDir });
+            // An infrastructure error (the run could not happen at all) counts as failed.
+            run.then(result => { state = result.status; }, () => { state = "failed"; });
+            return run;
         };
-        // Start the run immediately
-        resultPromise = startRun(args);
+        let 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
+                // Fail fast rather than wait on a participant that is still running.
                 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);
+                resultPromise = startRun(newArgs ? { ...lastArgs, ...newArgs } : lastArgs);
                 return handle;
             },
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trama-dev/session",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -29,10 +29,13 @@
     "LICENSE"
   ],
   "os": ["darwin", "linux"],
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "dependencies": {
-    "@trama-dev/runtime": "0.1.5"
+    "@trama-dev/runtime": "0.2.0"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0"
+    "@types/node": "^26.6.6"
   }
 }