@nettee/beacon 0.1.8 → 0.1.9

package/README.md

@@ -48,6 +48,7 @@ Copy the files under [`examples`](examples) into a private Beacon home and repla
 ```text
 ~/.beacon/
 ├── config.yaml
+├── runtime.env
 ├── secrets.json
 └── profiles/
     └── example/
@@ -59,9 +60,27 @@ Protect the home and secret file before running Beacon:
 
 ```sh
 chmod 700 /Users/USERNAME/.beacon
+test ! -e /Users/USERNAME/.beacon/runtime.env || chmod 600 /Users/USERNAME/.beacon/runtime.env
 chmod 600 /Users/USERNAME/.beacon/secrets.json
 ```
 
+`runtime.env` is optional. When present, Beacon loads every `KEY=VALUE` entry
+once at startup and passes it to every Pi Run. This gives launchd deployments a
+deterministic runtime environment without executing interactive shell files such
+as `.zshrc`:
+
+```dotenv
+GRAFANA_READER_TOKEN_PROD=replace-me
+```
+
+The file must be owned by the Beacon user with mode `0600`. Blank lines and
+lines beginning with `#` are ignored; values are literal and never evaluated as
+shell syntax. Duplicate or invalid names, malformed entries, and reserved
+process variables such as `PATH`, `NODE_OPTIONS`, `BEACON_*`, and `FEISHU_*`
+fail startup. A missing file is treated as an empty runtime environment. Changes
+take effect after Beacon restarts. Beacon does not log or persist values from
+this file, but every configured Profile and Pi Run receives them.
+
 Configure a dedicated absolute Pi session root in `config.yaml`:
 
 ```yaml
@@ -76,7 +95,7 @@ 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.
+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 or runtime-environment 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.
 

package/dist/config/global.js

@@ -75,6 +75,7 @@ export async function loadGlobalConfig(path) {
         homeDirectory,
         profilesDirectory,
         secretsPath: resolve(homeDirectory, "secrets.json"),
+        runtimeEnvironmentPath: resolve(homeDirectory, "runtime.env"),
         pi: {
             executable,
             codingAgentDirectory,

package/dist/config/runtime-environment.js

@@ -0,0 +1,91 @@
+import { readFile, stat } from "node:fs/promises";
+const variableNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const reservedVariableNames = new Set([
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "SHELL",
+    "TMPDIR",
+    "LANG",
+    "LC_ALL",
+    "TERM",
+    "COLORTERM",
+    "SSH_AUTH_SOCK",
+    "XDG_CONFIG_HOME",
+    "XDG_CACHE_HOME",
+    "GH_CONFIG_DIR",
+    "NODE_OPTIONS",
+    "PI_CODING_AGENT_DIR",
+    "PI_CODING_AGENT_SESSION_DIR",
+    "PI_PACKAGE_DIR",
+    "PI_OFFLINE",
+    "PI_TELEMETRY",
+]);
+export function assertRuntimeEnvironmentKey(key) {
+    if (!variableNamePattern.test(key)) {
+        throw new Error(`Invalid runtime environment variable name: ${key}`);
+    }
+    if (reservedVariableNames.has(key) ||
+        key.startsWith("BEACON_") ||
+        key.startsWith("FEISHU_")) {
+        throw new Error(`Runtime environment variable is reserved: ${key}`);
+    }
+}
+function parseRuntimeEnvironment(raw, path) {
+    const environment = {};
+    const lines = raw.replace(/^\uFEFF/, "").split(/\r?\n/);
+    for (const [index, line] of lines.entries()) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const separator = line.indexOf("=");
+        if (separator < 0) {
+            throw new Error(`Invalid runtime environment entry at ${path}:${index + 1}: expected KEY=VALUE`);
+        }
+        const key = line.slice(0, separator).trim();
+        assertRuntimeEnvironmentKey(key);
+        if (Object.hasOwn(environment, key)) {
+            throw new Error(`Duplicate runtime environment variable at ${path}:${index + 1}: ${key}`);
+        }
+        environment[key] = line.slice(separator + 1).trim();
+    }
+    return environment;
+}
+export async function loadRuntimeEnvironment(path) {
+    let metadata;
+    try {
+        metadata = await stat(path);
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return {};
+        }
+        throw new Error(`Cannot inspect Beacon runtime environment file at ${path}`, {
+            cause: error,
+        });
+    }
+    if (!metadata.isFile()) {
+        throw new Error(`Beacon runtime environment path is not a file: ${path}`);
+    }
+    if ((metadata.mode & 0o777) !== 0o600) {
+        throw new Error(`Beacon runtime environment file must have mode 0600: ${path}`);
+    }
+    if (typeof process.getuid === "function" &&
+        metadata.uid !== process.getuid()) {
+        throw new Error(`Beacon runtime environment file must be owned by the current user: ${path}`);
+    }
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new Error(`Cannot read Beacon runtime environment file at ${path}`, {
+            cause: error,
+        });
+    }
+    return parseRuntimeEnvironment(raw, path);
+}

package/dist/doctor.js

@@ -1,10 +1,12 @@
 import { loadGlobalConfig } from "./config/global.js";
 import { loadProfileRegistry } from "./config/registry.js";
+import { loadRuntimeEnvironment } from "./config/runtime-environment.js";
 import { loadFeishuCredentials } from "./config/secrets.js";
 import { createFeishuGateway } from "./feishu/gateway.js";
 import { runPiAgent } from "./runtime/pi-rpc.js";
 export async function runDoctor(configPath) {
     const global = await loadGlobalConfig(configPath);
+    const runtimeEnvironment = await loadRuntimeEnvironment(global.runtimeEnvironmentPath);
     const profiles = await loadProfileRegistry(global.profilesDirectory);
     for (const profile of profiles) {
         const credentials = await loadFeishuCredentials(profile.id, global.secretsPath);
@@ -20,6 +22,7 @@ export async function runDoctor(configPath) {
             timeoutMs: global.runs.timeoutSeconds * 1_000,
             terminateGraceMs: global.runs.terminateGraceSeconds * 1_000,
             environment: { PI_CODING_AGENT_DIR: global.pi.codingAgentDirectory },
+            runtimeEnvironment,
         });
         if (result.text !== "BEACON_PI_RPC_OK") {
             throw new Error(`Pi readiness returned unexpected text for Profile ${profile.id}: ${JSON.stringify(result.text)}`);

package/dist/manual-trigger.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { loadGlobalConfig } from "./config/global.js";
 import { loadProfileRegistry } from "./config/registry.js";
+import { loadRuntimeEnvironment } from "./config/runtime-environment.js";
 import { renderFinalOutcomeAsText } from "./outcome/content.js";
 import { startOutcomeServer } from "./outcome/server.js";
 import { createPiRunOrchestrator } from "./run/create-pi-orchestrator.js";
@@ -15,6 +16,7 @@ export async function runManualTrigger(configPath, profileId, input, output = wr
     if (!input.trim())
         throw new Error("Manual Trigger input must not be empty");
     const global = await loadGlobalConfig(configPath);
+    const runtimeEnvironment = await loadRuntimeEnvironment(global.runtimeEnvironmentPath);
     const profiles = await loadProfileRegistry(global.profilesDirectory);
     const profile = profiles.find((candidate) => candidate.id === profileId);
     if (!profile)
@@ -38,6 +40,7 @@ export async function runManualTrigger(configPath, profileId, input, output = wr
         };
         const orchestrator = createPiRunOrchestrator({
             config: global,
+            runtimeEnvironment,
             profile,
             store,
             queue: new RunQueue(global.runs.maxConcurrent, global.runs.maxQueued),

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

@@ -16,6 +16,7 @@ export function createPiRunOrchestrator(options) {
             environment: {
                 PI_CODING_AGENT_DIR: options.config.pi.codingAgentDirectory,
             },
+            runtimeEnvironment: options.runtimeEnvironment,
         }),
         delivery: options.delivery,
     });

package/dist/runtime/pi-rpc.js

@@ -3,6 +3,7 @@ import { chmod, mkdir } from "node:fs/promises";
 import { isAbsolute } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
+import { assertRuntimeEnvironmentKey } from "../config/runtime-environment.js";
 export class PiRuntimeError extends Error {
     code;
     constructor(code, message, options) {
@@ -86,13 +87,18 @@ const inheritedEnvironmentKeys = [
     "PI_OFFLINE",
     "PI_TELEMETRY",
 ];
-function buildPiEnvironment(outcome, configured = {}) {
+function buildPiEnvironment(outcome, configured = {}, runtimeEnvironment = {}) {
     const environment = {};
     for (const key of inheritedEnvironmentKeys) {
         const value = process.env[key];
         if (value !== undefined)
             environment[key] = value;
     }
+    for (const [key, value] of Object.entries(runtimeEnvironment)) {
+        assertRuntimeEnvironmentKey(key);
+        if (value !== undefined)
+            environment[key] = value;
+    }
     for (const [key, value] of Object.entries(configured)) {
         if (!inheritedEnvironmentKeys.includes(key)) {
             throw new Error(`Pi environment key is not allowlisted: ${key}`);
@@ -167,7 +173,7 @@ export async function runPiAgent(request, options = {}) {
     }
     const child = spawn(executable, buildArguments(request), {
         cwd: request.workspace,
-        env: buildPiEnvironment(request.outcome, options.environment),
+        env: buildPiEnvironment(request.outcome, options.environment, options.runtimeEnvironment),
         stdio: ["pipe", "pipe", "pipe"],
     });
     const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });

package/dist/schedule-trigger.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { loadGlobalConfig } from "./config/global.js";
 import { loadProfileRegistry } from "./config/registry.js";
+import { loadRuntimeEnvironment } from "./config/runtime-environment.js";
 import { loadFeishuCredentials } from "./config/secrets.js";
 import { createFeishuGateway } from "./feishu/gateway.js";
 import { startOutcomeServer } from "./outcome/server.js";
@@ -50,6 +51,7 @@ export async function triggerScheduleOnce(options) {
 }
 export async function runScheduleTrigger(configPath, profileId, scheduleId) {
     const global = await loadGlobalConfig(configPath);
+    const runtimeEnvironment = await loadRuntimeEnvironment(global.runtimeEnvironmentPath);
     const profiles = await loadProfileRegistry(global.profilesDirectory);
     const profile = profiles.find((candidate) => candidate.id === profileId);
     if (!profile)
@@ -61,6 +63,7 @@ export async function runScheduleTrigger(configPath, profileId, scheduleId) {
         const store = new TriggerStore(profile.directory, profile.id);
         const orchestrator = createPiRunOrchestrator({
             config: global,
+            runtimeEnvironment,
             profile,
             store,
             queue: new RunQueue(global.runs.maxConcurrent, global.runs.maxQueued),

package/dist/service.js

@@ -1,5 +1,6 @@
 import { loadGlobalConfig } from "./config/global.js";
 import { loadProfileRegistry } from "./config/registry.js";
+import { loadRuntimeEnvironment } from "./config/runtime-environment.js";
 import { loadFeishuCredentials } from "./config/secrets.js";
 import { createFeishuGateway } from "./feishu/gateway.js";
 import { createFeishuMessagePipeline } from "./feishu/message-pipeline.js";
@@ -29,6 +30,7 @@ function shutdownController() {
 }
 export async function runBeacon(configPath) {
     const global = await loadGlobalConfig(configPath);
+    const runtimeEnvironment = await loadRuntimeEnvironment(global.runtimeEnvironmentPath);
     const profiles = await loadProfileRegistry(global.profilesDirectory);
     const credentials = await Promise.all(profiles.map((profile) => loadFeishuCredentials(profile.id, global.secretsPath)));
     const outcomes = await startOutcomeServer();
@@ -46,6 +48,7 @@ export async function runBeacon(configPath) {
         const store = new TriggerStore(profile.directory, profile.id);
         const orchestrator = createPiRunOrchestrator({
             config: global,
+            runtimeEnvironment,
             profile,
             store,
             queue,

package/package.json

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