parasor 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "parasor",
+  "version": "0.1.0",
+  "description": "Web-based multi-client terminal multiplexer with PTY sharing.",
+  "keywords": [
+    "terminal",
+    "multiplexer",
+    "pty",
+    "web-terminal",
+    "browser-terminal",
+    "terminal-sharing",
+    "remote-access",
+    "remote-shell",
+    "xterm",
+    "tmux"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "akibe",
+    "url": "https://github.com/akibe"
+  },
+  "homepage": "https://github.com/artcodec-hq/parasor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/artcodec-hq/parasor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/artcodec-hq/parasor/issues"
+  },
+  "type": "module",
+  "bin": {
+    "parasor": "./bin/parasor.mjs"
+  },
+  "main": "./server/index.js",
+  "files": [
+    "bin",
+    "server",
+    "web",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.19.0",
+    "@hono/node-ws": "^1.3.0",
+    "@parcel/watcher": "^2.5.6",
+    "@xterm/headless": "6.1.0-beta.197",
+    "hono": "^4.12.0",
+    "ignore": "^7.0.5",
+    "node-pty": "1.2.0-beta.12",
+    "proper-lockfile": "^4.1.2",
+    "qrcode-terminal": "^0.12.0",
+    "write-file-atomic": "^7.0.1",
+    "yauzl": "^3.3.0",
+    "@parasor/shared": "0.0.1"
+  },
+  "bundleDependencies": [
+    "@parasor/shared"
+  ]
+}

package/server/agent-detector/agent-state-store.d.ts

@@ -0,0 +1,23 @@
+import type { AgentState } from "@parasor/shared";
+interface AgentStateStoreOptions {
+    dir: string;
+    fileName?: string;
+}
+interface GetStatesOptions {
+    liveSessionIds?: Iterable<string>;
+}
+export declare class AgentStateStore {
+    private states;
+    private readonly filePath;
+    constructor({ dir, fileName }: AgentStateStoreOptions);
+    getStates(options?: GetStatesOptions): Record<string, AgentState>;
+    set(state: AgentState): void;
+    replace(states: Record<string, AgentState>): void;
+    remove(sessionId: string): void;
+    prune(liveSessionIds: Iterable<string>): void;
+    private load;
+    private persist;
+    private write;
+}
+export {};
+//# sourceMappingURL=agent-state-store.d.ts.map

package/server/agent-detector/agent-state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-state-store.d.ts","sourceRoot":"","sources":["../../src/agent-detector/agent-state-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAIV,UAAU,EACX,MAAM,iBAAiB,CAAC;AAwBzB,UAAU,sBAAsB;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,gBAAgB;IACxB,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,EAAE,GAAG,EAAE,QAA6B,EAAE,EAAE,sBAAsB;IAK1E,SAAS,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;IAOjE,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAK5B,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,IAAI;IAKjD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAK/B,KAAK,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI;IAW7C,OAAO,CAAC,IAAI;IAkBZ,OAAO,CAAC,OAAO;IAYf,OAAO,CAAC,KAAK;CAYd"}

package/server/agent-detector/agent-state-store.js

@@ -0,0 +1,110 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const FILE_VERSION = 1;
+const LIFECYCLES = new Set([
+    "running",
+    "waiting",
+    "completed",
+    "idle",
+    "unknown",
+]);
+const SOURCES = new Set([
+    "hook",
+    "notify",
+    "output",
+    "activity",
+]);
+const CONFIDENCES = new Set(["high", "medium", "low"]);
+export class AgentStateStore {
+    states = new Map();
+    filePath;
+    constructor({ dir, fileName = "agent-state.json" }) {
+        this.filePath = join(dir, fileName);
+        this.load();
+    }
+    getStates(options) {
+        if (options?.liveSessionIds) {
+            this.prune(options.liveSessionIds);
+        }
+        return Object.fromEntries(this.states.entries());
+    }
+    set(state) {
+        this.states.set(state.sessionId, state);
+        this.persist();
+    }
+    replace(states) {
+        this.states = new Map(Object.entries(states));
+        this.persist();
+    }
+    remove(sessionId) {
+        if (!this.states.delete(sessionId))
+            return;
+        this.persist();
+    }
+    prune(liveSessionIds) {
+        const live = new Set(liveSessionIds);
+        let changed = false;
+        for (const sessionId of this.states.keys()) {
+            if (live.has(sessionId))
+                continue;
+            this.states.delete(sessionId);
+            changed = true;
+        }
+        if (changed)
+            this.persist();
+    }
+    load() {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.filePath, "utf8"));
+        }
+        catch {
+            return;
+        }
+        if (!isRecord(parsed) || parsed.version !== FILE_VERSION)
+            return;
+        if (!isRecord(parsed.states))
+            return;
+        for (const [sessionId, state] of Object.entries(parsed.states)) {
+            if (!isAgentState(state))
+                continue;
+            if (state.sessionId !== sessionId)
+                continue;
+            this.states.set(sessionId, state);
+        }
+    }
+    persist() {
+        try {
+            this.write();
+        }
+        catch (error) {
+            console.warn(`[agent-state-store] failed to persist agent state: ${error.message}`);
+        }
+    }
+    write() {
+        mkdirSync(dirname(this.filePath), { recursive: true, mode: 0o700 });
+        const payload = {
+            version: FILE_VERSION,
+            states: Object.fromEntries(this.states.entries()),
+        };
+        const tmpPath = `${this.filePath}.${process.pid}.tmp`;
+        writeFileSync(tmpPath, `${JSON.stringify(payload, null, 2)}\n`, {
+            mode: 0o600,
+        });
+        renameSync(tmpPath, this.filePath);
+    }
+}
+function isAgentState(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.sessionId === "string" &&
+        LIFECYCLES.has(value.lifecycle) &&
+        SOURCES.has(value.source) &&
+        CONFIDENCES.has(value.confidence) &&
+        typeof value.detectedAt === "number" &&
+        Number.isFinite(value.detectedAt));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=agent-state-store.js.map

package/server/agent-detector/agent-state-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-state-store.js","sourceRoot":"","sources":["../../src/agent-detector/agent-state-store.ts"],"names":[],"mappings":"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"}

package/server/agent-detector/detector.d.ts

@@ -0,0 +1,80 @@
+import type { AgentSignalConfidence, AgentSignalSource, AgentState } from "@parasor/shared";
+/**
+ * Diagnostic trace events emitted by the detector for the debug recorder.
+ * Captures the silent return paths inside {@link AgentDetector.feed} and
+ * {@link AgentDetector.applyObservation} so a reproduction can show *why*
+ * an expected state never landed (e.g. output regex matched `waiting` but
+ * was blocked by a stronger hook source, or a hook landed but lost the
+ * priority race).
+ */
+export type DetectorTraceEvent = {
+    kind: "feed-skip-source";
+    sessionId: string;
+    current: AgentSignalSource;
+    currentLifecycle: AgentState["lifecycle"];
+} | {
+    kind: "feed-control-only";
+    sessionId: string;
+} | {
+    kind: "feed-observed";
+    sessionId: string;
+    lifecycle: AgentState["lifecycle"];
+    sampleTail: string;
+} | {
+    kind: "applied-skip-source";
+    sessionId: string;
+    incoming: AgentSignalSource;
+    incomingLifecycle: AgentState["lifecycle"];
+    current: AgentSignalSource;
+    currentLifecycle: AgentState["lifecycle"];
+};
+type DetectorTraceCallback = (event: DetectorTraceEvent) => void;
+interface DetectorOptions {
+    idleTimeoutMs?: number;
+    now?: () => number;
+    onTrace?: DetectorTraceCallback;
+}
+interface FeedOptions {
+    observeOutput?: boolean;
+}
+export interface AgentObservation {
+    lifecycle: AgentState["lifecycle"];
+    source: AgentSignalSource;
+    confidence: AgentSignalConfidence;
+}
+type StateChangeCallback = (state: AgentState) => void;
+export declare class AgentDetector {
+    private states;
+    private idleTimers;
+    private listeners;
+    private idleTimeoutMs;
+    private now;
+    private onTrace;
+    constructor(options?: DetectorOptions);
+    onStateChange(callback: StateChangeCallback): void;
+    getStates(): Record<string, AgentState>;
+    restoreStates(states: Record<string, AgentState>): void;
+    feed(sessionId: string, data: string, options?: FeedOptions): void;
+    removeSession(sessionId: string): void;
+    /**
+     * Push a state change from outside the PTY-output fast path. Used by the
+     * `parasor notify` CLI / IPC bridge so that hook-driven agents (Claude
+     * Code, Codex, custom wrappers) can report state directly instead of
+     * relying on output-pattern matching.
+     *
+     * Once a session has received any external state, it is marked as
+     * hook/notify-managed and weaker PTY output observations become a no-op
+     * for it until the session is cleared. No idle timer is set here; the
+     * matching hook/notify transition is expected to push completed/idle
+     * explicitly.
+     */
+    setExternalState(sessionId: string, state: AgentObservation): void;
+    dispose(): void;
+    private applyObservation;
+    private isWeakerSource;
+    private clearIdleTimer;
+    private scheduleOutputIdle;
+}
+export declare function sanitizeTerminalOutput(data: string): string;
+export {};
+//# sourceMappingURL=detector.d.ts.map

package/server/agent-detector/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../src/agent-detector/detector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,iBAAiB,EACjB,UAAU,EACX,MAAM,iBAAiB,CAAC;AAsBzB;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CAC3C,GACD;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,IAAI,EAAE,eAAe,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;CACpB,GACD;IACE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,iBAAiB,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IAC3C,OAAO,EAAE,iBAAiB,CAAC;IAC3B,gBAAgB,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CAC3C,CAAC;AAEN,KAAK,qBAAqB,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAEjE,UAAU,eAAe;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED,UAAU,WAAW;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,UAAU,EAAE,qBAAqB,CAAC;CACnC;AAED,KAAK,mBAAmB,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAcvD,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,UAAU,CAAoD;IACtE,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,GAAG,CAAe;IAC1B,OAAO,CAAC,OAAO,CAAoC;gBAEvC,OAAO,CAAC,EAAE,eAAe;IAMrC,aAAa,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAIlD,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;IAIvC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,IAAI;IA2BvD,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IA4DlE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKtC;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAKlE,OAAO,IAAI,IAAI;IAQf,OAAO,CAAC,gBAAgB;IAqCxB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,kBAAkB;CAa3B;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM3D"}

package/server/agent-detector/detector.js

@@ -0,0 +1,219 @@
+const ATTENTION_PATTERNS = [
+    /\(y\/n\)\s*$/i,
+    /\[Y\/n\]\s*$/,
+    /waiting for input/i,
+    /Press Enter/i,
+];
+const COMPLETED_PATTERNS = [
+    /(?:^|\n)\s*❯\s*$/u,
+    /(?:^|\n)\s*>\s*$/u,
+    /(?:^|\n)\s*\$\s*$/u,
+];
+// biome-ignore lint/suspicious/noControlCharactersInRegex: terminal OSC escapes are control-sequence delimiters we intentionally strip.
+const OSC_SEQUENCE = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: terminal CSI escapes are control-sequence delimiters we intentionally strip.
+const CSI_SEQUENCE = /\u001b\[[0-?]*[ -/]*[@-~]/g;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: remaining ANSI ESC sequences are intentionally stripped.
+const ESC_SEQUENCE = /\u001b[@-_]/g;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: remaining C0/DEL control bytes are intentionally stripped from terminal text.
+const OTHER_CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f]/g;
+// Last N chars of sanitized output to attach to feed-observed traces.
+// Long enough to capture a prompt suffix or "Press Enter" line without
+// blowing up the debug log.
+const TRACE_SAMPLE_TAIL_CHARS = 120;
+const SOURCE_PRIORITY = {
+    activity: 0,
+    output: 1,
+    notify: 2,
+    hook: 3,
+};
+export class AgentDetector {
+    states = new Map();
+    idleTimers = new Map();
+    listeners = [];
+    idleTimeoutMs;
+    now;
+    onTrace;
+    constructor(options) {
+        this.idleTimeoutMs = options?.idleTimeoutMs ?? 30_000;
+        this.now = options?.now ?? (() => Date.now());
+        this.onTrace = options?.onTrace;
+    }
+    onStateChange(callback) {
+        this.listeners.push(callback);
+    }
+    getStates() {
+        return Object.fromEntries(this.states.entries());
+    }
+    restoreStates(states) {
+        for (const timer of this.idleTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.idleTimers.clear();
+        this.states.clear();
+        for (const state of Object.values(states)) {
+            let restored = state;
+            if (state.source === "output" && state.lifecycle !== "idle") {
+                const now = this.now();
+                if (state.detectedAt + this.idleTimeoutMs <= now) {
+                    restored = {
+                        ...state,
+                        lifecycle: "idle",
+                        confidence: "medium",
+                        detectedAt: now,
+                    };
+                }
+            }
+            this.states.set(restored.sessionId, restored);
+            if (restored.source === "output" && restored.lifecycle !== "idle") {
+                this.scheduleOutputIdle(restored.sessionId, restored.detectedAt);
+            }
+        }
+    }
+    feed(sessionId, data, options) {
+        const current = this.states.get(sessionId);
+        if (options?.observeOutput === false) {
+            this.clearIdleTimer(sessionId);
+            if (current?.source === "output" && current.lifecycle !== "idle") {
+                this.applyObservation(sessionId, {
+                    lifecycle: "idle",
+                    source: "output",
+                    confidence: "medium",
+                });
+            }
+            return;
+        }
+        if (current && this.isWeakerSource("output", current.source)) {
+            this.onTrace?.({
+                kind: "feed-skip-source",
+                sessionId,
+                current: current.source,
+                currentLifecycle: current.lifecycle,
+            });
+            return;
+        }
+        const sanitized = sanitizeTerminalOutput(data);
+        const lifecycle = detectOutputLifecycle(sanitized);
+        const hasMeaningfulOutput = /[^\s]/u.test(sanitized);
+        if (!lifecycle && !hasMeaningfulOutput) {
+            if (process.env.PARASOR_AGENT_DEBUG === "1") {
+                // eslint-disable-next-line no-console
+                console.error(`[agent-detector] session=${sessionId.slice(0, 8)} ignore control-only chunk`);
+            }
+            this.onTrace?.({ kind: "feed-control-only", sessionId });
+            return;
+        }
+        this.clearIdleTimer(sessionId);
+        const observed = lifecycle ?? "running";
+        this.applyObservation(sessionId, {
+            lifecycle: observed,
+            source: "output",
+            confidence: "medium",
+        });
+        if (lifecycle) {
+            this.onTrace?.({
+                kind: "feed-observed",
+                sessionId,
+                lifecycle: observed,
+                sampleTail: sanitized
+                    .slice(-TRACE_SAMPLE_TAIL_CHARS)
+                    .replace(/\s+/g, " ")
+                    .trim(),
+            });
+        }
+        this.scheduleOutputIdle(sessionId, this.now());
+    }
+    removeSession(sessionId) {
+        this.states.delete(sessionId);
+        this.clearIdleTimer(sessionId);
+    }
+    /**
+     * Push a state change from outside the PTY-output fast path. Used by the
+     * `parasor notify` CLI / IPC bridge so that hook-driven agents (Claude
+     * Code, Codex, custom wrappers) can report state directly instead of
+     * relying on output-pattern matching.
+     *
+     * Once a session has received any external state, it is marked as
+     * hook/notify-managed and weaker PTY output observations become a no-op
+     * for it until the session is cleared. No idle timer is set here; the
+     * matching hook/notify transition is expected to push completed/idle
+     * explicitly.
+     */
+    setExternalState(sessionId, state) {
+        this.clearIdleTimer(sessionId);
+        this.applyObservation(sessionId, state);
+    }
+    dispose() {
+        for (const timer of this.idleTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.idleTimers.clear();
+        this.states.clear();
+    }
+    applyObservation(sessionId, observation) {
+        const current = this.states.get(sessionId);
+        if (current && this.isWeakerSource(observation.source, current.source)) {
+            this.onTrace?.({
+                kind: "applied-skip-source",
+                sessionId,
+                incoming: observation.source,
+                incomingLifecycle: observation.lifecycle,
+                current: current.source,
+                currentLifecycle: current.lifecycle,
+            });
+            return;
+        }
+        const nextState = {
+            sessionId,
+            ...observation,
+            detectedAt: this.now(),
+        };
+        if (current &&
+            current.lifecycle === nextState.lifecycle &&
+            current.source === nextState.source &&
+            current.confidence === nextState.confidence) {
+            return;
+        }
+        this.states.set(sessionId, nextState);
+        for (const listener of this.listeners) {
+            listener(nextState);
+        }
+    }
+    isWeakerSource(incoming, current) {
+        return SOURCE_PRIORITY[incoming] < SOURCE_PRIORITY[current];
+    }
+    clearIdleTimer(sessionId) {
+        const timer = this.idleTimers.get(sessionId);
+        if (timer) {
+            clearTimeout(timer);
+            this.idleTimers.delete(sessionId);
+        }
+    }
+    scheduleOutputIdle(sessionId, detectedAt) {
+        const delay = Math.max(0, detectedAt + this.idleTimeoutMs - this.now());
+        this.idleTimers.set(sessionId, setTimeout(() => {
+            this.applyObservation(sessionId, {
+                lifecycle: "idle",
+                source: "output",
+                confidence: "medium",
+            });
+        }, delay));
+    }
+}
+export function sanitizeTerminalOutput(data) {
+    return data
+        .replace(OSC_SEQUENCE, "")
+        .replace(CSI_SEQUENCE, "")
+        .replace(ESC_SEQUENCE, "")
+        .replace(OTHER_CONTROL_CHARS, "");
+}
+function detectOutputLifecycle(sanitized) {
+    if (ATTENTION_PATTERNS.some((pattern) => pattern.test(sanitized))) {
+        return "waiting";
+    }
+    if (COMPLETED_PATTERNS.some((pattern) => pattern.test(sanitized))) {
+        return "completed";
+    }
+    return null;
+}
+//# sourceMappingURL=detector.js.map

package/server/agent-detector/detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.js","sourceRoot":"","sources":["../../src/agent-detector/detector.ts"],"names":[],"mappings":"AAMA,MAAM,kBAAkB,GAAG;IACzB,eAAe;IACf,cAAc;IACd,oBAAoB;IACpB,cAAc;CACf,CAAC;AACF,MAAM,kBAAkB,GAAG;IACzB,mBAAmB;IACnB,mBAAmB;IACnB,oBAAoB;CACrB,CAAC;AACF,wIAAwI;AACxI,MAAM,YAAY,GAAG,8CAA8C,CAAC;AACpE,wIAAwI;AACxI,MAAM,YAAY,GAAG,4BAA4B,CAAC;AAClD,oHAAoH;AACpH,MAAM,YAAY,GAAG,cAAc,CAAC;AACpC,yIAAyI;AACzI,MAAM,mBAAmB,GAAG,qCAAqC,CAAC;AAwDlE,sEAAsE;AACtE,uEAAuE;AACvE,4BAA4B;AAC5B,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAEpC,MAAM,eAAe,GAAsC;IACzD,QAAQ,EAAE,CAAC;IACX,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;CACR,CAAC;AAEF,MAAM,OAAO,aAAa;IAChB,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAC;IACvC,UAAU,GAAG,IAAI,GAAG,EAAyC,CAAC;IAC9D,SAAS,GAA0B,EAAE,CAAC;IACtC,aAAa,CAAS;IACtB,GAAG,CAAe;IAClB,OAAO,CAAoC;IAEnD,YAAY,OAAyB;QACnC,IAAI,CAAC,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,MAAM,CAAC;QACtD,IAAI,CAAC,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;IAClC,CAAC;IAED,aAAa,CAAC,QAA6B;QACzC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAED,SAAS;QACP,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,aAAa,CAAC,MAAkC;QAC9C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;YAC7C,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAEpB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1C,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;gBAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACvB,IAAI,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,aAAa,IAAI,GAAG,EAAE,CAAC;oBACjD,QAAQ,GAAG;wBACT,GAAG,KAAK;wBACR,SAAS,EAAE,MAAM;wBACjB,UAAU,EAAE,QAAQ;wBACpB,UAAU,EAAE,GAAG;qBAChB,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC9C,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,IAAI,QAAQ,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;gBAClE,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;YACnE,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,CAAC,SAAiB,EAAE,IAAY,EAAE,OAAqB;QACzD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,OAAO,EAAE,aAAa,KAAK,KAAK,EAAE,CAAC;YACrC,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;YAC/B,IAAI,OAAO,EAAE,MAAM,KAAK,QAAQ,IAAI,OAAO,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;gBACjE,IAAI,CAAC,gBAAgB,CAAC,SAAS,EAAE;oBAC/B,SAAS,EAAE,MAAM;oBACjB,MAAM,EAAE,QAAQ;oBAChB,UAAU,EAAE,QAAQ;iBACrB,CAAC,CAAC;YACL,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,IAAI,EAAE,kBAAkB;gBACxB,SAAS;gBACT,OAAO,EAAE,OAAO,CAAC,MAAM;gBACvB,gBAAgB,EAAE,OAAO,CAAC,SAAS;aACpC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,SAAS,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;QACnD,MAAM,mBAAmB,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,CAAC,SAAS,IAAI,CAAC,mBAAmB,EAAE,CAAC;YACvC,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,KAAK,GAAG,EAAE,CAAC;gBAC5C,sCAAsC;gBACtC,OAAO,CAAC,KAAK,CACX,4BAA4B,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,4BAA4B,CAC9E,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,SAAS,EAAE,CAAC,CAAC;YACzD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAE/B,MAAM,QAAQ,GAA4B,SAAS,IAAI,SAAS,CAAC;QACjE,IAAI,CAAC,gBAAgB,CAAC,SAAS,EAAE;YAC/B,SAAS,EAAE,QAAQ;YACnB,MAAM,EAAE,QAAQ;YAChB,UAAU,EAAE,QAAQ;SACrB,CAAC,CAAC;QACH,IAAI,SAAS,EAAE,CAAC;YACd,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,IAAI,EAAE,eAAe;gBACrB,SAAS;gBACT,SAAS,EAAE,QAAQ;gBACnB,UAAU,EAAE,SAAS;qBAClB,KAAK,CAAC,CAAC,uBAAuB,CAAC;qBAC/B,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;qBACpB,IAAI,EAAE;aACV,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,aAAa,CAAC,SAAiB;QAC7B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC9B,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,SAAiB,EAAE,KAAuB;QACzD,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QAC/B,IAAI,CAAC,gBAAgB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO;QACL,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;YAC7C,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAEO,gBAAgB,CACtB,SAAiB,EACjB,WAA6B;QAE7B,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACvE,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,IAAI,EAAE,qBAAqB;gBAC3B,SAAS;gBACT,QAAQ,EAAE,WAAW,CAAC,MAAM;gBAC5B,iBAAiB,EAAE,WAAW,CAAC,SAAS;gBACxC,OAAO,EAAE,OAAO,CAAC,MAAM;gBACvB,gBAAgB,EAAE,OAAO,CAAC,SAAS;aACpC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAe;YAC5B,SAAS;YACT,GAAG,WAAW;YACd,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE;SACvB,CAAC;QACF,IACE,OAAO;YACP,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,SAAS;YACzC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM;YACnC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,UAAU,EAC3C,CAAC;YACD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QACtC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;IAEO,cAAc,CACpB,QAA2B,EAC3B,OAA0B;QAE1B,OAAO,eAAe,CAAC,QAAQ,CAAC,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC9D,CAAC;IAEO,cAAc,CAAC,SAAiB;QACtC,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAEO,kBAAkB,CAAC,SAAiB,EAAE,UAAkB;QAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,UAAU,CAAC,GAAG,CACjB,SAAS,EACT,UAAU,CAAC,GAAG,EAAE;YACd,IAAI,CAAC,gBAAgB,CAAC,SAAS,EAAE;gBAC/B,SAAS,EAAE,MAAM;gBACjB,MAAM,EAAE,QAAQ;gBAChB,UAAU,EAAE,QAAQ;aACrB,CAAC,CAAC;QACL,CAAC,EAAE,KAAK,CAAC,CACV,CAAC;IACJ,CAAC;CACF;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,IAAI;SACR,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;SACzB,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;SACzB,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC;SACzB,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,qBAAqB,CAC5B,SAAiB;IAEjB,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;QAClE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;QAClE,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/server/agent-detector/event-map.d.ts

@@ -0,0 +1,25 @@
+import type { AgentObservation } from "./detector.js";
+declare const AGENT_NAME_LIST: readonly ["claude", "codex", "manual"];
+export type AgentName = (typeof AGENT_NAME_LIST)[number];
+/**
+ * Outcome of normalizing a hook event:
+ *   - `{ kind: "state", state }` -- apply the observation to the session
+ *   - `{ kind: "noop" }`          -- recognized but intentionally ignored
+ *                                    (e.g. Claude's SessionStart, which is
+ *                                    only used for PID registration in
+ *                                    other implementations)
+ *   - `{ kind: "unknown" }`       -- event name not in the dictionary; the
+ *                                    caller should reject with a 4xx
+ */
+export type EventMapResult = {
+    kind: "state";
+    state: AgentObservation;
+} | {
+    kind: "noop";
+} | {
+    kind: "unknown";
+};
+export declare function isKnownAgent(name: string): name is AgentName;
+export declare function mapEventType(agent: AgentName, event: string): EventMapResult;
+export {};
+//# sourceMappingURL=event-map.d.ts.map

package/server/agent-detector/event-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-map.d.ts","sourceRoot":"","sources":["../../src/agent-detector/event-map.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAatD,QAAA,MAAM,eAAe,wCAAyC,CAAC;AAC/D,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAGzD;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAyGxB,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,SAAS,CAE5D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAuB5E"}