@relay-baton/shared 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DongGeon Lee
+
+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/dist/constants.d.ts

@@ -0,0 +1,54 @@
+export declare const SESSION_DIR = ".ai-session";
+/**
+ * v2.6 multi-session workspace. Named work items live under
+ * `.ai-session/sessions/<name>/`; the legacy flat `.ai-session/` IS the
+ * `default` work item (so existing repos need no migration). The active pointer
+ * + work-item list live in `.ai-session/workspace.json`.
+ */
+export declare const WORKSPACE_FILE = "workspace.json";
+export declare const SESSIONS_SUBDIR = "sessions";
+export declare const DEFAULT_SESSION = "default";
+/**
+ * v1.0 stability contract. These are the frozen schema versions for the two
+ * persisted contracts relay-baton owns. Bump ONLY on a breaking shape change;
+ * loaders normalize older payloads up to the current version.
+ */
+export declare const CONFIG_VERSION = 1;
+export declare const SESSION_SCHEMA_VERSION = 1;
+/**
+ * v2.0 artifact schema registry. Current on-disk schema version for each
+ * versioned artifact relay-baton owns. The migration tooling (`migrate
+ * --check`, `doctor --deep`) compares what it finds on disk against these.
+ * Bump a value ONLY on a breaking shape change and register a migrator.
+ * Artifacts without a schemaVersion field are treated as legacy v1.
+ */
+export declare const ARTIFACT_SCHEMA_VERSIONS: {
+    readonly sessionJson: 1;
+    readonly checkpoints: 1;
+    readonly gitBaseline: 1;
+    readonly conversation: 1;
+};
+export type VersionedArtifact = keyof typeof ARTIFACT_SCHEMA_VERSIONS;
+export declare const SESSION_FILES: {
+    readonly task: "task.md";
+    readonly state: "state.md";
+    readonly compactState: "compact-state.md";
+    readonly handoff: "handoff.md";
+    readonly plan: "plan.md";
+    readonly decisions: "decisions.md";
+    readonly changedFiles: "changed-files.md";
+    readonly repoMap: "repo-map.md";
+    readonly commandsLog: "commands.log";
+    readonly errors: "errors.md";
+    readonly testResults: "test-results.md";
+    readonly fullDiff: "full-diff.patch";
+    readonly contextBudget: "context-budget.json";
+    readonly gitBaseline: "git-baseline.json";
+    readonly sessionJson: "session.json";
+    readonly conversation: "conversation.jsonl";
+    readonly checkpoints: "checkpoints.jsonl";
+    readonly usage: "usage.jsonl";
+};
+export declare const TRUNCATE_MARKER = "[TRUNCATED by relay-baton token diet: original content exceeded section budget]";
+export declare const IGNORE_DIRS: Set<string>;
+export declare const SKIP_DIFF_PATTERNS: RegExp[];

package/dist/constants.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKIP_DIFF_PATTERNS = exports.IGNORE_DIRS = exports.TRUNCATE_MARKER = exports.SESSION_FILES = exports.ARTIFACT_SCHEMA_VERSIONS = exports.SESSION_SCHEMA_VERSION = exports.CONFIG_VERSION = exports.DEFAULT_SESSION = exports.SESSIONS_SUBDIR = exports.WORKSPACE_FILE = exports.SESSION_DIR = void 0;
+exports.SESSION_DIR = ".ai-session";
+/**
+ * v2.6 multi-session workspace. Named work items live under
+ * `.ai-session/sessions/<name>/`; the legacy flat `.ai-session/` IS the
+ * `default` work item (so existing repos need no migration). The active pointer
+ * + work-item list live in `.ai-session/workspace.json`.
+ */
+exports.WORKSPACE_FILE = "workspace.json";
+exports.SESSIONS_SUBDIR = "sessions";
+exports.DEFAULT_SESSION = "default";
+/**
+ * v1.0 stability contract. These are the frozen schema versions for the two
+ * persisted contracts relay-baton owns. Bump ONLY on a breaking shape change;
+ * loaders normalize older payloads up to the current version.
+ */
+exports.CONFIG_VERSION = 1;
+exports.SESSION_SCHEMA_VERSION = 1;
+/**
+ * v2.0 artifact schema registry. Current on-disk schema version for each
+ * versioned artifact relay-baton owns. The migration tooling (`migrate
+ * --check`, `doctor --deep`) compares what it finds on disk against these.
+ * Bump a value ONLY on a breaking shape change and register a migrator.
+ * Artifacts without a schemaVersion field are treated as legacy v1.
+ */
+exports.ARTIFACT_SCHEMA_VERSIONS = {
+    sessionJson: 1,
+    checkpoints: 1,
+    gitBaseline: 1,
+    conversation: 1,
+};
+exports.SESSION_FILES = {
+    task: "task.md",
+    state: "state.md",
+    compactState: "compact-state.md",
+    handoff: "handoff.md",
+    plan: "plan.md",
+    decisions: "decisions.md",
+    changedFiles: "changed-files.md",
+    repoMap: "repo-map.md",
+    commandsLog: "commands.log",
+    errors: "errors.md",
+    testResults: "test-results.md",
+    fullDiff: "full-diff.patch",
+    contextBudget: "context-budget.json",
+    gitBaseline: "git-baseline.json",
+    sessionJson: "session.json",
+    // v0.7 — append-only conversation event log (Agent Room groundwork).
+    conversation: "conversation.jsonl",
+    // v1.7 — append-only execution checkpoints (guarded execution workflow).
+    checkpoints: "checkpoints.jsonl",
+    // v2.4 — append-only local usage ledger (token/quota proxy; never transmitted).
+    usage: "usage.jsonl",
+};
+exports.TRUNCATE_MARKER = "[TRUNCATED by relay-baton token diet: original content exceeded section budget]";
+exports.IGNORE_DIRS = new Set([
+    ".git",
+    "node_modules",
+    "bin",
+    "obj",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    "coverage",
+    ".ai-session",
+]);
+exports.SKIP_DIFF_PATTERNS = [
+    /(^|\/)package-lock\.json$/,
+    /(^|\/)pnpm-lock\.yaml$/,
+    /(^|\/)yarn\.lock$/,
+    /(^|\/)dist\//,
+    /(^|\/)build\//,
+    /\.min\.js$/,
+];

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./constants";
+export * from "./safe-path";

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./constants"), exports);
+__exportStar(require("./safe-path"), exports);

package/dist/safe-path.d.ts

@@ -0,0 +1,40 @@
+/**
+ * v2.2 — untrusted-bundle / path-traversal safety.
+ *
+ * Externally-received bundles and archives carry a manifest whose `target`
+ * paths we must NOT trust. A malicious manifest could point a `target` at an
+ * absolute path (`/etc/passwd`, `C:\Windows\...`), escape the bundle root with
+ * `..`, or route through a symlink that resolves outside the root. Resolving
+ * such a target and reading it would turn `inspect` into an arbitrary-file-read
+ * (and SHA-256 oracle) primitive.
+ *
+ * `resolveWithin` is the single chokepoint: it rejects absolute targets, `..`
+ * escapes, and symlinked escapes, returning a path that is provably inside
+ * `root`. Anything suspicious returns `null` — callers treat that as "unsafe"
+ * rather than reading the file.
+ */
+/**
+ * Per-file size cap applied when an inspector reads an untrusted file to verify
+ * it (8 MiB). Curated handoff/session artifacts are small; a manifest claiming
+ * a huge file is a red flag and would also let a hostile bundle exhaust memory
+ * during verification.
+ */
+export declare const MAX_INSPECT_FILE_BYTES: number;
+export type UnsafeReason = "absolute" | "escapes-root" | "symlink-escape";
+export interface ResolveWithinResult {
+    /** Absolute path inside `root`, or null when the target is unsafe. */
+    abs: string | null;
+    /** POSIX-style relative path from root (for display), even when unsafe. */
+    rel: string;
+    reason?: UnsafeReason;
+}
+/**
+ * Resolve a manifest `target` against `root`, refusing anything that would
+ * escape `root`. `root` is assumed trusted (it is where we put the bundle).
+ *
+ * Rejects, in order:
+ *  - absolute `target` (`/x`, `C:\x`, `\\server\share`)
+ *  - normalized path that escapes `root` via `..`
+ *  - a path whose existing prefix is a symlink pointing outside `root`
+ */
+export declare function resolveWithin(root: string, target: string): ResolveWithinResult;

package/dist/safe-path.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_INSPECT_FILE_BYTES = void 0;
+exports.resolveWithin = resolveWithin;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * v2.2 — untrusted-bundle / path-traversal safety.
+ *
+ * Externally-received bundles and archives carry a manifest whose `target`
+ * paths we must NOT trust. A malicious manifest could point a `target` at an
+ * absolute path (`/etc/passwd`, `C:\Windows\...`), escape the bundle root with
+ * `..`, or route through a symlink that resolves outside the root. Resolving
+ * such a target and reading it would turn `inspect` into an arbitrary-file-read
+ * (and SHA-256 oracle) primitive.
+ *
+ * `resolveWithin` is the single chokepoint: it rejects absolute targets, `..`
+ * escapes, and symlinked escapes, returning a path that is provably inside
+ * `root`. Anything suspicious returns `null` — callers treat that as "unsafe"
+ * rather than reading the file.
+ */
+/**
+ * Per-file size cap applied when an inspector reads an untrusted file to verify
+ * it (8 MiB). Curated handoff/session artifacts are small; a manifest claiming
+ * a huge file is a red flag and would also let a hostile bundle exhaust memory
+ * during verification.
+ */
+exports.MAX_INSPECT_FILE_BYTES = 8 * 1024 * 1024;
+/**
+ * Resolve a manifest `target` against `root`, refusing anything that would
+ * escape `root`. `root` is assumed trusted (it is where we put the bundle).
+ *
+ * Rejects, in order:
+ *  - absolute `target` (`/x`, `C:\x`, `\\server\share`)
+ *  - normalized path that escapes `root` via `..`
+ *  - a path whose existing prefix is a symlink pointing outside `root`
+ */
+function resolveWithin(root, target) {
+    const relForDisplay = toPosix(target);
+    if (path.isAbsolute(target) || /^[a-zA-Z]:[\\/]/.test(target) || /^\\\\/.test(target)) {
+        return { abs: null, rel: relForDisplay, reason: "absolute" };
+    }
+    const rootResolved = path.resolve(root);
+    const candidate = path.resolve(rootResolved, target);
+    const rel = path.relative(rootResolved, candidate);
+    if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        return { abs: null, rel: relForDisplay, reason: "escapes-root" };
+    }
+    // Symlink escape: walk the existing prefix and ensure realpath stays inside.
+    if (escapesViaSymlink(rootResolved, candidate)) {
+        return { abs: null, rel: relForDisplay, reason: "symlink-escape" };
+    }
+    return { abs: candidate, rel: toPosix(rel) };
+}
+function escapesViaSymlink(rootResolved, candidate) {
+    let realRoot;
+    try {
+        realRoot = fs.realpathSync(rootResolved);
+    }
+    catch {
+        // Root itself missing — nothing to verify against; treat as in-root.
+        return false;
+    }
+    // Find the deepest existing ancestor of `candidate` and realpath it.
+    let existing = candidate;
+    while (!fs.existsSync(existing)) {
+        const parent = path.dirname(existing);
+        if (parent === existing)
+            return false; // reached filesystem root
+        existing = parent;
+    }
+    let realExisting;
+    try {
+        realExisting = fs.realpathSync(existing);
+    }
+    catch {
+        return false;
+    }
+    const rel = path.relative(realRoot, realExisting);
+    return rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel);
+}
+function toPosix(p) {
+    return p.split(path.sep).join("/").replace(/\\/g, "/");
+}

package/dist/types.d.ts

@@ -0,0 +1,199 @@
+export type AgentId = "codex" | "claude" | "opencode" | "gemini" | "aider" | "cursor";
+export type DietProfileName = "off" | "lite" | "balanced" | "caveman" | "ultra";
+export type SessionStatus = "initialized" | "running" | "fallback_detected" | "handoff_ready" | "running_fallback" | "planning" | "plan_ready" | "executing" | "compressing" | "completed" | "failed";
+export type WorkflowMode = "fallback" | "plan-execute";
+export interface DietProfile {
+    maxHandoffChars: number;
+    maxDiffChars: number;
+    maxRepoMapChars: number;
+    maxLogTailChars: number;
+    maxStateChars: number;
+    maxErrorChars: number;
+    /** v0.5 plan-execute: max chars for plan.md. Defaults to maxHandoffChars when absent. */
+    maxPlanChars?: number;
+}
+export interface AuthPolicy {
+    mode: "cli-session" | "api-key";
+    allowApiKeyEnv: boolean;
+    warnIfApiKeyEnvDetected: boolean;
+    blockedEnvVars: string[];
+}
+export interface AgentConfig {
+    command: string;
+    args: string[];
+}
+export interface RelayBatonConfig {
+    /**
+     * v1.0 frozen-contract marker. Absent = legacy (treated as version 1).
+     * See CONFIG_VERSION in constants.
+     */
+    configVersion?: number;
+    primaryAgent: AgentId;
+    fallbackAgent: AgentId;
+    agents: Record<string, AgentConfig>;
+    fallbackPatterns: string[];
+    commands: {
+        test: string;
+        build: string;
+    };
+    authPolicy: AuthPolicy;
+    tokenDiet: {
+        enabled: boolean;
+        profile: DietProfileName;
+        outputCompression: boolean;
+        profiles: Record<string, DietProfile>;
+    };
+    planExecute?: {
+        defaultPlanner: AgentId;
+        defaultExecutor: AgentId;
+        maxPlanChars?: number;
+    };
+    contextCompression?: {
+        enabled: boolean;
+        /** Auto-compress inside `run` when the threshold is crossed. */
+        auto: boolean;
+        /** Fraction (0..1) of the profile budget that triggers compression. */
+        threshold: number;
+        /** Keep the pre-compression commands.log as commands.log.full.<timestamp>. */
+        rotateRawArtifacts: boolean;
+        /**
+         * v0.9: adaptive per-agent thresholds. When the active agent has an entry,
+         * it overrides the global `threshold`. Agents with larger context windows
+         * can run hotter (higher threshold) before compaction kicks in.
+         */
+        perAgent?: Partial<Record<AgentId, number>>;
+    };
+    hooks?: {
+        /** Shell commands run before building a handoff (in order). */
+        preHandoff?: string[];
+        /** Shell commands run after an agent finishes a run/handoff (in order). */
+        postExecute?: string[];
+    };
+    guardrails?: {
+        /** Block when recorded execution checkpoints reach this count. */
+        maxSteps?: number;
+        /** Block when the working tree has at least this many changed files. */
+        maxChangedFiles?: number;
+        /** Block when handoff chars / maxHandoffChars reaches this ratio (0..1). */
+        maxBudgetRatio?: number;
+        /** Surface that mutating steps still require explicit human confirmation. */
+        requireConfirmation?: boolean;
+    };
+}
+export interface SessionMeta {
+    /**
+     * v1.0 frozen-contract marker. Absent = legacy (treated as version 1).
+     * See SESSION_SCHEMA_VERSION in constants.
+     */
+    schemaVersion?: number;
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    repoRoot: string;
+    task: string;
+    status: SessionStatus;
+    primaryAgent: AgentId;
+    fallbackAgent: AgentId;
+    activeAgent: AgentId | "none";
+    lastAgent: AgentId | "none";
+    fallbackReason: string | null;
+    lastError: string | null;
+    tokenDietProfile: DietProfileName;
+    /** ISO timestamp when the most recent `run` / `handoff` command kicked off. */
+    startedAt?: string;
+    /** ISO timestamp when the session transitioned to `completed` or `failed`. */
+    endedAt?: string;
+    /** endedAt - startedAt, in milliseconds. Cleared on a new run/handoff. */
+    durationMs?: number;
+    /** Total number of handoff documents successfully written in this session. */
+    handoffCount?: number;
+    /** Which workflow produced this session. Absent = legacy fallback flow. */
+    workflowMode?: WorkflowMode;
+    /** Agent that authored .ai-session/plan.md. */
+    planAuthor?: AgentId | null;
+    /** Agent that executes from the plan. */
+    executor?: AgentId | null;
+    /** ISO timestamp when plan.md passed its quality gate. */
+    planFinalizedAt?: string;
+    /** ISO timestamp when the execute phase started. */
+    executeStartedAt?: string;
+}
+export interface AgentRunInput {
+    task: string;
+    repoRoot: string;
+    sessionDir: string;
+    prompt?: string;
+    dietProfile?: DietProfileName;
+    allowApiKeyEnv?: boolean;
+}
+export interface AgentCommand {
+    command: string;
+    args: string[];
+    cwd: string;
+}
+export interface AgentEvent {
+    type: "stdout" | "stderr" | "exit" | "error" | "fallback";
+    text?: string;
+    code?: number;
+    reason?: string;
+}
+export interface BudgetSnapshot {
+    profile: DietProfileName;
+    maxHandoffChars: number;
+    used: {
+        handoff: number;
+        repoMap: number;
+        fullDiff: number;
+        commandsLog: number;
+        compactState: number;
+    };
+    truncated: boolean;
+}
+export type ConversationRole = "user" | "claude" | "codex" | "relay-baton";
+export type ConversationEventKind = "message" | "command" | "prompt_preview" | "agent_run" | "plan" | "execute" | "review" | "diagnose" | "handoff" | "status" | "budget";
+export interface ConversationEvent {
+    /** v2.0 versioned-contract marker; absent in pre-v2.0 events (legacy v1). */
+    schemaVersion?: number;
+    /** Stable id, e.g. "evt_<uuid>". */
+    id: string;
+    /** ISO timestamp. */
+    ts: string;
+    /** Owning session (SessionMeta.id) when known. */
+    sessionId?: string;
+    role: ConversationRole;
+    kind: ConversationEventKind;
+    /** Token-diet-friendly summary. NEVER a full diff/log — reference instead. */
+    text: string;
+    /** Pointers to .ai-session artifacts (relative names), not inlined blobs. */
+    refs?: Record<string, string>;
+    /** Kind-specific, all optional. */
+    meta?: {
+        agent?: AgentId;
+        diet?: DietProfileName;
+        exitCode?: number;
+        confirmed?: boolean;
+        stepRefs?: string[];
+        [k: string]: unknown;
+    };
+}
+export interface BatonProject {
+    id: string;
+    name: string;
+    path: string;
+    createdAt: string;
+    updatedAt: string;
+    lastUsedAt?: string;
+    defaultDiet?: DietProfileName;
+    primaryAgent?: AgentId;
+    fallbackAgent?: AgentId;
+    /**
+     * v0.8: project-level fallback-pattern overlay. When set and non-empty,
+     * these are appended to the global config.fallbackPatterns (deduped,
+     * case-insensitive) for runs scoped to this project.
+     */
+    fallbackPatterns?: string[];
+}
+export interface ProjectRegistryData {
+    activeProjectId: string | null;
+    projects: BatonProject[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@relay-baton/shared",
+  "version": "1.0.0",
+  "description": "Shared utilities for relay-baton (safe-path guards and common helpers)",
+  "license": "MIT",
+  "author": "DongGeon Lee",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dgl1231/relay-baton.git",
+    "directory": "packages/shared"
+  },
+  "homepage": "https://github.com/dgl1231/relay-baton#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "echo \"no tests\" && exit 0"
+  }
+}