@gtc6244/immediacy-daemon 0.1.0

package/dist/src/permission-gate.js

@@ -0,0 +1,93 @@
+/**
+ * Permission gate: holds deferred tool-call decisions until the phone answers.
+ *
+ * Shared by every agent backend. Default-deny on timeout (§5) so a backgrounded
+ * or disconnected phone can never leave a tool call hanging — or worse, let one
+ * through.
+ */
+export class PermissionGate {
+    timeoutMs;
+    pending = new Map();
+    constructor(timeoutMs = 120_000) {
+        this.timeoutMs = timeoutMs;
+    }
+    /** Register a deferred request; resolves when the phone responds or times out. */
+    wait(requestId) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(requestId);
+                resolve("deny"); // default-deny
+            }, this.timeoutMs);
+            // Don't let a pending prompt hold the process open.
+            timer.unref?.();
+            this.pending.set(requestId, { resolve, timer });
+        });
+    }
+    /** Resolve a pending request from a `permission.respond`. No-op if unknown. */
+    resolve(requestId, decision) {
+        const p = this.pending.get(requestId);
+        if (!p)
+            return false;
+        clearTimeout(p.timer);
+        this.pending.delete(requestId);
+        p.resolve(decision);
+        return true;
+    }
+    /** Deny everything outstanding (e.g. on agent stop). */
+    denyAll() {
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.resolve("deny");
+        }
+        this.pending.clear();
+    }
+}
+/**
+ * Question gate: the AskUserQuestion analogue of {@link PermissionGate}. Holds a
+ * deferred `AskUserQuestion` call until the user picks answers on some client.
+ *
+ * Two differences from the permission gate:
+ *  - it resolves with the picked {@link QuestionResolution}, not allow/deny —
+ *    those answers become the tool's result fed back to the model;
+ *  - the timeout is long (a clarifying question is a deliberate ask the user may
+ *    take minutes to answer). On timeout it resolves `null`, which the agent
+ *    turns into a "no answer" denial so a disconnected client can't hang the
+ *    SDK subprocess forever.
+ */
+export class QuestionGate {
+    timeoutMs;
+    pending = new Map();
+    constructor(timeoutMs = 3_600_000) {
+        this.timeoutMs = timeoutMs;
+    }
+    /** Register a deferred question; resolves when the user answers or times out. */
+    wait(requestId) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(requestId);
+                resolve(null); // default: no answer
+            }, this.timeoutMs);
+            timer.unref?.();
+            this.pending.set(requestId, { resolve, timer });
+        });
+    }
+    /** Resolve a pending question from a `question.respond`. No-op if unknown. */
+    resolve(requestId, resolution) {
+        const p = this.pending.get(requestId);
+        if (!p)
+            return false;
+        clearTimeout(p.timer);
+        this.pending.delete(requestId);
+        p.resolve(resolution);
+        return true;
+    }
+    /** Abandon everything outstanding (e.g. on agent stop) → treated as no answer. */
+    denyAll() {
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.resolve(null);
+        }
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=permission-gate.js.map

package/dist/src/permission-gate.js.map

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

package/dist/src/permission-scope.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Permission scoping: turn a single gated tool call into a reusable "allow all"
+ * rule, and test future calls against stored rules.
+ *
+ * This is the server-side half of the phone's "Allow all" button. When a client
+ * answers a permission request with `allow_all`, the daemon derives a {@link
+ * AllowRule} from that exact `(tool, input)` and persists it (see allowlist.ts,
+ * daemon-global + on disk). Every later call is checked against the stored rules
+ * *before* it defers to the phone — a match auto-approves, so "additional
+ * requests that fall into the same category" go through untouched.
+ *
+ * A rule is deliberately coarse — a *category*, not the exact call:
+ *   - host — any web request to the same *site*: the registrable domain (eTLD+1)
+ *            of the URL, so a grant made on docs.example.com also covers
+ *            www./api./example.com (any page/path on any subdomain of the site).
+ *   - dir  — any file or shell call whose target resolves inside a directory
+ *            (a file grant covers the folder it lives in; a Bash grant covers
+ *            the directory the command runs in — its cwd, the worktree).
+ *   - tool — any call of a tool we can't bound to a host or directory
+ *            (MCP tools, WebSearch, unknown tools): allow that tool wholesale.
+ *
+ * Derivation is most-specific-first: a URL yields a host rule, a path (or a
+ * shell tool, scoped to its cwd) yields a dir rule, and everything else falls to
+ * a tool rule. Matching mirrors that, and is symlink-safe for dir rules (it goes
+ * through fs-scope's `isInside`), so a link inside a granted folder can't smuggle
+ * a call out of it.
+ */
+export type AllowRule = {
+    kind: "host";
+    host: string;
+} | {
+    kind: "dir";
+    path: string;
+} | {
+    kind: "tool";
+    tool: string;
+};
+/**
+ * Derive the rule an "Allow all" on this call should create, or `null` when the
+ * call can't be generalized (e.g. a shape we don't model) — in which case the
+ * client's `allow_all` degrades to a plain one-shot allow.
+ */
+export declare function deriveRule(tool: string, input: Record<string, unknown>, worktreePath: string): AllowRule | null;
+/** True when any stored rule already covers this call. */
+export declare function anyRuleMatches(rules: readonly AllowRule[], tool: string, input: Record<string, unknown>, worktreePath: string): boolean;
+/** True when a single rule covers this call. */
+export declare function ruleMatches(rule: AllowRule, tool: string, input: Record<string, unknown>, worktreePath: string): boolean;
+/** Stable identity for dedup + storage; two calls in the same category share it. */
+export declare function ruleKey(rule: AllowRule): string;
+/** One-line human description for the log line and the admin list. */
+export declare function describeRule(rule: AllowRule): string;
+/** Coerce arbitrary parsed JSON into a valid AllowRule, or null if malformed. */
+export declare function sanitizeRule(input: unknown): AllowRule | null;
+/**
+ * Root URL — scheme + host (e.g. `https://example.com`) — of the first usable
+ * URL field, or null. Used for a human "web request to …" summary: the path,
+ * query, and JSON wrapping are dropped so the notification stays readable.
+ */
+export declare function webRootUrl(input: Record<string, unknown>): string | null;
+/**
+ * The registrable domain ("site") of a hostname: its public suffix plus one
+ * label — example.com, relay.link, foo.co.uk. Host rules are keyed on this so a
+ * grant made on any subdomain (docs./api./www.) covers the whole site, which is
+ * what a user means by "allow this site."
+ *
+ * This is a pragmatic approximation of the Public Suffix List, not the full
+ * list: the public suffix is taken as one label, except for a curated set of
+ * two-label suffixes (see {@link MULTI_PART_SUFFIXES}) where it is two — both
+ * common ccTLDs (co.uk, com.au) and popular *private* app-hosting suffixes
+ * (github.io, vercel.app, …) where each subdomain is a DIFFERENT owner, so
+ * folding to the bare suffix would let a grant on one user's site silently
+ * cover every site on the platform. An unknown two-label suffix still folds one
+ * label too far — that only ever *broadens* a grant (never narrows it), which is
+ * acceptable because grants are user-initiated and revocable. IP literals and
+ * single-label hosts (localhost, intranet names) are returned verbatim.
+ */
+export declare function siteOf(host: string): string;

package/dist/src/permission-scope.js

@@ -0,0 +1,244 @@
+/**
+ * Permission scoping: turn a single gated tool call into a reusable "allow all"
+ * rule, and test future calls against stored rules.
+ *
+ * This is the server-side half of the phone's "Allow all" button. When a client
+ * answers a permission request with `allow_all`, the daemon derives a {@link
+ * AllowRule} from that exact `(tool, input)` and persists it (see allowlist.ts,
+ * daemon-global + on disk). Every later call is checked against the stored rules
+ * *before* it defers to the phone — a match auto-approves, so "additional
+ * requests that fall into the same category" go through untouched.
+ *
+ * A rule is deliberately coarse — a *category*, not the exact call:
+ *   - host — any web request to the same *site*: the registrable domain (eTLD+1)
+ *            of the URL, so a grant made on docs.example.com also covers
+ *            www./api./example.com (any page/path on any subdomain of the site).
+ *   - dir  — any file or shell call whose target resolves inside a directory
+ *            (a file grant covers the folder it lives in; a Bash grant covers
+ *            the directory the command runs in — its cwd, the worktree).
+ *   - tool — any call of a tool we can't bound to a host or directory
+ *            (MCP tools, WebSearch, unknown tools): allow that tool wholesale.
+ *
+ * Derivation is most-specific-first: a URL yields a host rule, a path (or a
+ * shell tool, scoped to its cwd) yields a dir rule, and everything else falls to
+ * a tool rule. Matching mirrors that, and is symlink-safe for dir rules (it goes
+ * through fs-scope's `isInside`), so a link inside a granted folder can't smuggle
+ * a call out of it.
+ */
+import { dirname, isAbsolute, resolve } from "node:path";
+import { isInside } from "./fs-scope.js";
+/** Shell tools run with `cwd = worktreePath`; a grant scopes to that directory. */
+const SHELL_TOOLS = new Set(["Bash", "BashOutput", "KillShell"]);
+/** Input fields that name a filesystem target (mirrors workspace-scope.ts). */
+const PATH_FIELDS = ["file_path", "path", "notebook_path"];
+/** Input fields that may carry a URL (WebFetch + browser/MCP tools). */
+const URL_FIELDS = ["url", "uri"];
+/**
+ * Derive the rule an "Allow all" on this call should create, or `null` when the
+ * call can't be generalized (e.g. a shape we don't model) — in which case the
+ * client's `allow_all` degrades to a plain one-shot allow.
+ */
+export function deriveRule(tool, input, worktreePath) {
+    const host = extractHost(input);
+    if (host)
+        return { kind: "host", host: siteOf(host) };
+    const dir = callDir(tool, input, worktreePath);
+    if (dir)
+        return { kind: "dir", path: dir };
+    // Nothing bound it to a host or a directory — allow the tool as a category.
+    return { kind: "tool", tool };
+}
+/** True when any stored rule already covers this call. */
+export function anyRuleMatches(rules, tool, input, worktreePath) {
+    return rules.some((r) => ruleMatches(r, tool, input, worktreePath));
+}
+/** True when a single rule covers this call. */
+export function ruleMatches(rule, tool, input, worktreePath) {
+    switch (rule.kind) {
+        case "host": {
+            const host = extractHost(input);
+            // Compare on the registrable domain, so any subdomain of the granted site
+            // matches (docs./api./www. all fold to the same eTLD+1).
+            return host !== null && siteOf(host) === rule.host;
+        }
+        case "dir": {
+            const dir = callDir(tool, input, worktreePath);
+            // Containment (not equality) so a grant on a folder also covers its
+            // subfolders; isInside canonicalizes symlinks on both sides.
+            return dir !== null && isInside(rule.path, dir);
+        }
+        case "tool":
+            return tool === rule.tool;
+    }
+}
+/** Stable identity for dedup + storage; two calls in the same category share it. */
+export function ruleKey(rule) {
+    switch (rule.kind) {
+        case "host":
+            return `host:${rule.host}`;
+        case "dir":
+            return `dir:${rule.path}`;
+        case "tool":
+            return `tool:${rule.tool}`;
+    }
+}
+/** One-line human description for the log line and the admin list. */
+export function describeRule(rule) {
+    switch (rule.kind) {
+        case "host":
+            return `all requests to ${rule.host}`;
+        case "dir":
+            return `all tool calls under ${rule.path}`;
+        case "tool":
+            return `all ${rule.tool} calls`;
+    }
+}
+/** Coerce arbitrary parsed JSON into a valid AllowRule, or null if malformed. */
+export function sanitizeRule(input) {
+    if (!input || typeof input !== "object")
+        return null;
+    const o = input;
+    if (o.kind === "host" && typeof o.host === "string" && o.host.trim())
+        // Fold through siteOf so freshly-derived and legacy exact-host rules
+        // (persisted before subdomain coverage existed) normalize to the same
+        // registrable domain — an old "www.example.com" grant loads as
+        // "example.com" and keeps working.
+        return { kind: "host", host: siteOf(o.host.trim().toLowerCase()) };
+    if (o.kind === "dir" && typeof o.path === "string" && o.path.trim())
+        return { kind: "dir", path: resolve(o.path) };
+    if (o.kind === "tool" && typeof o.tool === "string" && o.tool.trim())
+        return { kind: "tool", tool: o.tool };
+    return null;
+}
+/**
+ * The directory a call targets, for dir-rule derivation/matching:
+ *   - shell tools → their cwd (the worktree), since they run there;
+ *   - path tools  → the parent folder of the (worktree-resolved) target path;
+ *   - anything else → null (not directory-scoped).
+ */
+function callDir(tool, input, worktreePath) {
+    if (SHELL_TOOLS.has(tool))
+        return resolve(worktreePath);
+    const p = pathField(input);
+    if (p === null)
+        return null;
+    const abs = isAbsolute(p) ? resolve(p) : resolve(worktreePath, p);
+    return dirname(abs);
+}
+/** First usable (non-empty string) path field, else null. */
+function pathField(input) {
+    for (const f of PATH_FIELDS) {
+        const v = input[f];
+        if (typeof v === "string" && v.trim().length > 0)
+            return v;
+    }
+    return null;
+}
+/**
+ * Root URL — scheme + host (e.g. `https://example.com`) — of the first usable
+ * URL field, or null. Used for a human "web request to …" summary: the path,
+ * query, and JSON wrapping are dropped so the notification stays readable.
+ */
+export function webRootUrl(input) {
+    for (const f of URL_FIELDS) {
+        const v = input[f];
+        if (typeof v !== "string" || v.trim().length === 0)
+            continue;
+        try {
+            const u = new URL(v);
+            if (u.hostname)
+                return `${u.protocol}//${u.host}`;
+        }
+        catch {
+            /* not a parseable URL — fall through */
+        }
+    }
+    return null;
+}
+/** Lowercased hostname of the first usable URL field, or null. */
+function extractHost(input) {
+    for (const f of URL_FIELDS) {
+        const v = input[f];
+        if (typeof v !== "string" || v.trim().length === 0)
+            continue;
+        try {
+            const host = new URL(v).hostname.toLowerCase();
+            if (host)
+                return host;
+        }
+        catch {
+            /* not a parseable URL — fall through */
+        }
+    }
+    return null;
+}
+/**
+ * The registrable domain ("site") of a hostname: its public suffix plus one
+ * label — example.com, relay.link, foo.co.uk. Host rules are keyed on this so a
+ * grant made on any subdomain (docs./api./www.) covers the whole site, which is
+ * what a user means by "allow this site."
+ *
+ * This is a pragmatic approximation of the Public Suffix List, not the full
+ * list: the public suffix is taken as one label, except for a curated set of
+ * two-label suffixes (see {@link MULTI_PART_SUFFIXES}) where it is two — both
+ * common ccTLDs (co.uk, com.au) and popular *private* app-hosting suffixes
+ * (github.io, vercel.app, …) where each subdomain is a DIFFERENT owner, so
+ * folding to the bare suffix would let a grant on one user's site silently
+ * cover every site on the platform. An unknown two-label suffix still folds one
+ * label too far — that only ever *broadens* a grant (never narrows it), which is
+ * acceptable because grants are user-initiated and revocable. IP literals and
+ * single-label hosts (localhost, intranet names) are returned verbatim.
+ */
+export function siteOf(host) {
+    // Drop a trailing-dot FQDN ("example.com.") so it folds like "example.com"
+    // instead of yielding a bare-suffix rule ("com.") that mis-scopes matches.
+    const h = host.endsWith(".") ? host.slice(0, -1) : host;
+    if (isIpLiteral(h) || !h.includes("."))
+        return h;
+    const labels = h.split(".");
+    const suffixLabels = MULTI_PART_SUFFIXES.has(labels.slice(-2).join(".")) ? 2 : 1;
+    const take = suffixLabels + 1; // registrable domain = public suffix + 1 label
+    return labels.length <= take ? h : labels.slice(-take).join(".");
+}
+/** True for an IPv4 literal or a bracketed IPv6 host — never reduce these. */
+function isIpLiteral(host) {
+    return host.startsWith("[") || /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
+}
+/**
+ * Two-label suffixes treated as a single public suffix, so the label ABOVE them
+ * is the registrable domain — foo.co.uk folds to foo.co.uk (not co.uk), and
+ * alice.github.io folds to alice.github.io (not github.io). Two groups:
+ *
+ *   - ccTLD second-levels (co.uk, com.au, …) — the classic PSL case.
+ *   - private app-hosting suffixes (github.io, vercel.app, …) where each
+ *     subdomain is a separate tenant; without these a grant on one project's
+ *     site would auto-approve every site on the platform (a real trust widening
+ *     for a permission allowlist).
+ *
+ * Not exhaustive — the frequent ones a coding agent actually fetches. Anything
+ * not listed folds one label too far, which only broadens (never narrows) a
+ * user-initiated, revocable grant. See siteOf for the tradeoff.
+ */
+const MULTI_PART_SUFFIXES = new Set([
+    // ccTLD second-level domains
+    "co.uk", "org.uk", "gov.uk", "ac.uk", "me.uk", "net.uk", "sch.uk",
+    "com.au", "net.au", "org.au", "edu.au", "gov.au", "id.au",
+    "co.jp", "or.jp", "ne.jp", "ac.jp", "go.jp",
+    "co.nz", "org.nz", "net.nz", "govt.nz", "ac.nz",
+    "co.in", "net.in", "org.in", "gen.in", "firm.in", "ind.in",
+    "com.br", "net.br", "org.br", "gov.br",
+    "co.za", "org.za",
+    "com.cn", "net.cn", "org.cn", "gov.cn",
+    "co.kr", "or.kr",
+    "com.mx", "com.ar", "com.tr", "com.sg", "com.hk", "com.tw",
+    // Private app-hosting suffixes (per-subdomain tenancy — must NOT fold away)
+    "github.io", "gitlab.io", "githubusercontent.com",
+    "vercel.app", "netlify.app", "pages.dev", "workers.dev", "r2.dev",
+    "web.app", "firebaseapp.com", "appspot.com",
+    "herokuapp.com", "onrender.com", "fly.dev", "railway.app",
+    "azurewebsites.net", "cloudfront.net",
+    "blogspot.com", "wordpress.com", "readthedocs.io",
+    "repl.co", "replit.app", "glitch.me", "surge.sh", "ngrok.io",
+    "supabase.co",
+]);
+//# sourceMappingURL=permission-scope.js.map

package/dist/src/permission-scope.js.map

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

package/dist/src/ports.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Worktree-owned port discovery.
+ *
+ * When an agent runs `npm run dev` (or anything that binds a TCP port) inside
+ * its worktree, we want to surface that port to the operator so they can preview
+ * it in a local browser via a forwarded stream (see `forward.ts`).
+ *
+ * The authoritative signal is the OS, not the dev server's banner text: we ask
+ * `lsof` which processes are LISTENing on TCP, then correlate each listening
+ * process to a worktree by its working directory (`cwd`). A process whose `cwd`
+ * resolves inside a worktree path is attributed to that workspace — this catches
+ * servers launched in the interactive PTY and by the agent alike, and (because
+ * `cwd` survives it) a `npm run dev &` that gets reparented to launchd.
+ *
+ * The same attribution doubles as the security boundary: `forward.open` only
+ * dials ports that appear here, so a client cannot reach arbitrary loopback
+ * ports on the daemon box (the daemon's own WSS port, SSH, etc. never resolve to
+ * a worktree cwd, so they never appear).
+ */
+/** A discovered port attributed to a workspace. */
+export interface OwnedPort {
+    ws: string;
+    port: number;
+    addr: string;
+}
+/** What the scanner needs to know about live worktrees to attribute ports. */
+export interface WorktreeRef {
+    ws: string;
+    worktreePath: string;
+}
+/** Parse `host:port` (incl. IPv6 `[::1]:port` / `*:port`) → {addr, port}. */
+export declare function splitHostPort(name: string): {
+    addr: string;
+    port: number;
+} | null;
+/**
+ * One discovery pass: which worktree-owned ports are listening right now.
+ * Deduped by (ws, port); a port that binds both IPv4 and IPv6 collapses to one
+ * entry, preferring an explicit loopback address for display.
+ */
+export declare function scanOwnedPorts(worktrees: WorktreeRef[]): Promise<OwnedPort[]>;
+/**
+ * Polls `scanOwnedPorts` on an interval and fires `onChange` only when the set
+ * actually moves (a new server came up / one went away), so clients get an
+ * event on transitions rather than a steady heartbeat. Start it when at least
+ * one client is attached; stop it when the last one leaves.
+ */
+export declare class PortScanner {
+    private worktrees;
+    private onChange;
+    private timer;
+    private last;
+    private scanning;
+    /** A refresh() that landed during an in-flight scan; honored before tick ends. */
+    private rescanRequested;
+    constructor(worktrees: () => WorktreeRef[], onChange: (ports: OwnedPort[]) => void);
+    /** The most recent scan result (used to answer `forward.list` immediately). */
+    current: OwnedPort[];
+    start(): void;
+    stop(): void;
+    /**
+     * Force an out-of-band scan (e.g. a client just attached, or an agent turn
+     * finished). Guaranteed to yield a scan that started after this call: if one
+     * is already running, `rescanRequested` makes the in-flight loop run again
+     * rather than dropping the request.
+     */
+    refresh(): Promise<void>;
+    private tick;
+    /** Is `port` currently owned by `ws`? The forward-open security check. */
+    isOwned(ws: string, port: number): boolean;
+}