@nettee/beacon 0.1.2 → 0.1.3

package/README.md

@@ -61,6 +61,20 @@ chmod 700 /Users/USERNAME/.beacon
 chmod 600 /Users/USERNAME/.beacon/secrets.json
 ```
 
+Configure a dedicated absolute Pi session root in `config.yaml`:
+
+```yaml
+pi:
+  executable: /ABSOLUTE/PATH/TO/pi
+  coding_agent_directory: /Users/USERNAME/.pi/agent
+  session_directory: /Users/USERNAME/.beacon/sessions
+```
+
+`pi.session_directory` is optional for compatibility with configurations
+created by Beacon 0.1.2 and earlier; when omitted it defaults to `sessions/`
+beside `config.yaml`. When configured, it must be absolute. Beacon creates
+per-Run directories with mode `0700` when Pi starts.
+
 Configuration is strict: unknown YAML/JSON fields, YAML aliases or warnings, missing paths, duplicate Schedule IDs, invalid timezones/cron expressions, unsafe Prompt paths, permissive secret permissions, and missing Profile credentials all fail startup. Beacon validates all Profiles before opening a Feishu connection.
 
 Each Schedule uses a five-field cron expression and an IANA timezone. Its `delivery.chat_id` may identify either a direct chat or a group chat; Beacon deliberately does not infer or fall back to another destination. A newly discovered Schedule starts at the current time. After sleep or restart, overdue occurrences are reconciled and coalesced to the most recent one.
@@ -85,6 +99,30 @@ printf '%s\n' 'Summarize the workspace status.' | \
 
 Per-Profile state lives below `profiles/<profile-id>/state/`. Trigger claims, normalized inputs, Run state, Final Outcomes, Delivery state, and Schedule cursors use durable JSON snapshots. Records do not expire, and Beacon has no automatic cleanup task. Manually deleting state also deletes its deduplication memory.
 
+Every new business Run also owns a permanent Pi session. Its Run record stores
+both `sessionId` and `sessionPath`; the session ID is exactly the Beacon
+`runId`, and the path is the dedicated directory
+`<pi.session_directory>/<profile-id>/<runId>/`. Pi receives that mapping via
+`--session-dir`, `--session-id`, and a readable `Beacon <profile-id> <runId>`
+name. The directory contains the Pi JSONL session file and is never cleaned up
+by Beacon. A queued Run keeps the same mapping after restart. Queued records
+written by Beacon 0.1.2 or earlier are assigned the same deterministic mapping
+when recovered. Historical completed records remain readable and may omit the
+two session fields because those Runs were originally ephemeral.
+
+To locate a session from a reported `run_id`, first find its durable Run
+record, then inspect or export the sole JSONL file in `sessionPath`:
+
+```sh
+rg -l '"runId": "run_REPORTED_ID"' /Users/USERNAME/.beacon/profiles/*/state/triggers/*/record.json
+jq '.run | {runId, sessionId, sessionPath, state}' /ABSOLUTE/PATH/TO/record.json
+find /ABSOLUTE/SESSION/PATH -maxdepth 1 -name '*.jsonl' -print
+pi --export /ABSOLUTE/SESSION/PATH/TIMESTAMP_run_REPORTED_ID.jsonl run.html
+```
+
+`beacon doctor` keeps using `--no-session`, so its Pi smoke tests do not create
+diagnostic session files.
+
 Duplicate Feishu events and duplicate Schedule occurrences do not start a second Run. Active Runs interrupted by restart fail rather than rerun. Pending Delivery can resume, while a Delivery interrupted after its external call began fails without resending. Run and Delivery success are recorded independently. Beacon does not automatically retry either one.
 
 Secrets and ephemeral Run Capability tokens are excluded from persisted records and from the Pi environment except for the one Run-scoped Outcome capability.
@@ -131,7 +169,7 @@ installed `beacon` binary without using the source tree.
 `pnpm e2e:message` sends one synthetic Feishu direct message through an
 in-memory Gateway, the production message pipeline, and a real Pi model. The
 same in-memory Gateway captures the quoted reply without contacting Feishu. It defaults to
-`openai-codex/gpt-5.3-codex-spark`; override the runtime with
+`openai-codex/gpt-5.6-luna:low`; override the runtime with
 `BEACON_E2E_MESSAGE_PROVIDER`, `BEACON_E2E_MESSAGE_MODEL`,
 `BEACON_E2E_MESSAGE_PI_EXECUTABLE`, or
 `BEACON_E2E_MESSAGE_PI_CODING_AGENT_DIRECTORY`.

package/dist/config/global.js

@@ -1,6 +1,6 @@
 import { constants } from "node:fs";
 import { access, realpath, stat } from "node:fs/promises";
-import { dirname, isAbsolute, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { z } from "zod";
 import { parseStrictYaml } from "./yaml.js";
 const positiveInteger = z.number().int().positive().safe();
@@ -12,6 +12,7 @@ const globalDocumentSchema = z
         .object({
         executable: z.string().min(1),
         coding_agent_directory: z.string().min(1),
+        session_directory: z.string().min(1).optional(),
     })
         .strict(),
     runs: z
@@ -63,6 +64,10 @@ export async function loadGlobalConfig(path) {
     if (!isAbsolute(document.pi.coding_agent_directory)) {
         throw new Error("Pi coding agent directory must be absolute");
     }
+    if (document.pi.session_directory !== undefined &&
+        !isAbsolute(document.pi.session_directory)) {
+        throw new Error("Pi session directory path must be absolute");
+    }
     const executable = await assertFile(document.pi.executable, true);
     const codingAgentDirectory = await assertDirectory(document.pi.coding_agent_directory);
     return {
@@ -70,7 +75,13 @@ export async function loadGlobalConfig(path) {
         homeDirectory,
         profilesDirectory,
         secretsPath: resolve(homeDirectory, "secrets.json"),
-        pi: { executable, codingAgentDirectory },
+        pi: {
+            executable,
+            codingAgentDirectory,
+            // Keep version 1 configurations valid while moving sessions out of Pi's
+            // workspace-derived default hierarchy.
+            sessionDirectory: document.pi.session_directory ?? join(homeDirectory, "sessions"),
+        },
         runs: {
             maxConcurrent: document.runs.max_concurrent,
             maxQueued: document.runs.max_queued,

package/dist/run/create-pi-orchestrator.js

@@ -8,6 +8,7 @@ export function createPiRunOrchestrator(options) {
         queue: options.queue,
         outcomes: options.outcomes,
         beaconCliPath: fileURLToPath(new URL("../../dist/cli.js", import.meta.url)),
+        sessionDirectory: options.config.pi.sessionDirectory,
         runAgent: (request) => runPiAgent(request, {
             executable: options.config.pi.executable,
             timeoutMs: options.config.runs.timeoutSeconds * 1_000,

package/dist/run/orchestrator.js

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
+import { isAbsolute, join } from "node:path";
 import { PiRuntimeError } from "../runtime/pi-rpc.js";
 function promptFor(input) {
     if (input.kind === "manual") {
@@ -42,6 +43,9 @@ export class RunOrchestrator {
     id;
     constructor(options) {
         this.options = options;
+        if (!isAbsolute(options.sessionDirectory)) {
+            throw new Error("Pi session directory must be absolute");
+        }
         this.now = options.now ?? (() => new Date());
         this.id = options.id ?? randomUUID;
     }
@@ -52,6 +56,8 @@ export class RunOrchestrator {
         const timestamp = this.timestamp();
         return {
             runId,
+            sessionId: runId,
+            sessionPath: join(this.options.sessionDirectory, this.options.profile.id, runId),
             state,
             queuedAt: timestamp,
             ...(state === "failed" ? { finishedAt: timestamp } : {}),
@@ -136,10 +142,30 @@ export class RunOrchestrator {
         await this.deliver(triggerKey);
     }
     async execute(triggerKey, input, runId) {
-        await this.options.store.update(triggerKey, (current) => ({
-            ...current,
-            run: { ...current.run, state: "starting", startedAt: this.timestamp() },
-        }));
+        const record = await this.options.store.update(triggerKey, (current) => {
+            if (!current.run) {
+                throw new Error(`Cannot execute Trigger ${triggerKey} without a Run`);
+            }
+            const session = current.run.sessionId && current.run.sessionPath
+                ? {
+                    sessionId: current.run.sessionId,
+                    sessionPath: current.run.sessionPath,
+                }
+                : {
+                    // Migration for queued records written by Beacon <= 0.1.2.
+                    sessionId: current.run.runId,
+                    sessionPath: join(this.options.sessionDirectory, this.options.profile.id, current.run.runId),
+                };
+            return {
+                ...current,
+                run: {
+                    ...current.run,
+                    ...session,
+                    state: "starting",
+                    startedAt: this.timestamp(),
+                },
+            };
+        });
         await this.options.store.update(triggerKey, (current) => ({
             ...current,
             run: { ...current.run, state: "running" },
@@ -158,6 +184,11 @@ export class RunOrchestrator {
                     "Beacon ignores ordinary assistant final text for Delivery.",
                 ].join("\n"),
                 outcome: { ...submission.binding, cliPath: this.options.beaconCliPath },
+                session: {
+                    id: record.run.sessionId,
+                    path: record.run.sessionPath,
+                    name: `Beacon ${this.options.profile.id} ${runId}`,
+                },
             });
             const outcome = submission.take();
             await this.options.store.update(triggerKey, (current) => ({

package/dist/runtime/pi-rpc.js

@@ -1,4 +1,6 @@
 import { spawn } from "node:child_process";
+import { chmod, mkdir } from "node:fs/promises";
+import { isAbsolute } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 export class PiRuntimeError extends Error {
@@ -43,7 +45,15 @@ function collectText(message) {
         .trim();
 }
 function buildArguments(request) {
-    const args = ["--mode", "rpc", "--no-session", "--no-approve"];
+    const args = ["--mode", "rpc", "--no-approve"];
+    if (request.session) {
+        args.push("--session-dir", request.session.path, "--session-id", request.session.id);
+        if (request.session.name)
+            args.push("--name", request.session.name);
+    }
+    else {
+        args.push("--no-session");
+    }
     if (request.provider)
         args.push("--provider", request.provider);
     if (request.model)
@@ -124,6 +134,24 @@ export async function runPiAgent(request, options = {}) {
     if ((request.provider === undefined) !== (request.model === undefined)) {
         throw new Error("Pi Run provider and model must either both be set or both be omitted");
     }
+    if (request.session) {
+        if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(request.session.id)) {
+            throw new Error("Pi session ID is invalid");
+        }
+        if (!isAbsolute(request.session.path)) {
+            throw new Error("Pi session path must be absolute");
+        }
+        if (request.session.name !== undefined && !request.session.name.trim()) {
+            throw new Error("Pi session name must not be empty");
+        }
+        try {
+            await mkdir(request.session.path, { recursive: true, mode: 0o700 });
+            await chmod(request.session.path, 0o700);
+        }
+        catch (error) {
+            throw new PiRuntimeError("runtime_spawn_failed", `Cannot prepare Pi session directory: ${request.session.path}`, { cause: error });
+        }
+    }
     const executable = options.executable ?? "pi";
     const timeoutMs = options.timeoutMs ?? 5 * 60_000;
     const terminateGraceMs = options.terminateGraceMs ?? 1_000;

package/dist/state/trigger-store.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { chmod, mkdir, open, readdir, readFile, rename, } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import { z } from "zod";
 import { failureCodes, } from "../domain/types.js";
 const timestamp = z.string().datetime({ offset: true });
@@ -44,6 +44,15 @@ const inputSchema = z.discriminatedUnion("kind", [
 const runSchema = z
     .object({
     runId: z.string().min(1),
+    sessionId: z
+        .string()
+        .regex(/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/)
+        .optional(),
+    sessionPath: z
+        .string()
+        .min(1)
+        .refine(isAbsolute, "Pi session path must be absolute")
+        .optional(),
     state: z.enum(["queued", "starting", "running", "succeeded", "failed"]),
     queuedAt: timestamp,
     startedAt: timestamp.optional(),
@@ -96,6 +105,17 @@ function keyFor(profileId, sourceKey) {
 }
 function validateRecord(value) {
     const record = triggerRecordSchema.parse(value);
+    if (record.run &&
+        (record.run.sessionId === undefined) !==
+            (record.run.sessionPath === undefined)) {
+        throw new Error("Run record must contain both Pi sessionId and sessionPath or neither");
+    }
+    if (record.run?.sessionId &&
+        (record.run.sessionId !== record.run.runId ||
+            basename(record.run.sessionPath) !== record.run.runId ||
+            basename(dirname(record.run.sessionPath)) !== record.profileId)) {
+        throw new Error("Run Pi session identity must map to its Profile ID and Run ID");
+    }
     if (record.delivery && !record.finalOutcome) {
         throw new Error("Trigger record with Delivery must contain a Final Outcome");
     }

package/examples/config.yaml

@@ -3,6 +3,7 @@ profiles_directory: profiles
 pi:
   executable: /ABSOLUTE/PATH/TO/pi
   coding_agent_directory: /Users/USERNAME/.pi/agent
+  session_directory: /Users/USERNAME/.beacon/sessions
 runs:
   max_concurrent: 2
   max_queued: 100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nettee/beacon",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A single-host bridge from messaging and schedules to isolated agent runs",
   "license": "Apache-2.0",
   "repository": {