appduct 0.9.0

package/dist/commands/mcp.js

@@ -0,0 +1,98 @@
+/**
+ * `appduct mcp` (ARCHITECTURE.md §9, §10): starts a stdio MCP server that proxies the daemon RPC
+ * (auto-spawn applies, same as every other command). This is a hosted command like `daemon run`/
+ * `events` — it runs until the transport closes (client disconnected) or the process is
+ * interrupted — and its stdout is reserved entirely for MCP protocol frames, so unlike every other
+ * command it must never let `executeHostedCommand`'s default bootstrap render reach stdout (the
+ * dispatcher wires an `"interactive"` reporter for exactly this reason, same as `events`).
+ *
+ * The deep-link scheme (`--scheme`, `APPDUCT_SCHEME`, project/state config, `app.json` — see
+ * `scheme.ts`) is resolved once here at startup, and *not* finding one is not an error: see
+ * {@link resolveSchemeForServer}.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "../daemon/config.js";
+import { getStateDirPaths } from "../daemon/state-dir.js";
+import { createMcpServer } from "../mcp/server.js";
+import { resolveScheme } from "../scheme.js";
+/**
+ * Resolves the deep-link scheme for the server, *never* throwing.
+ *
+ * Unlike `appduct link`, an unresolved (or unresolvable) scheme must not stop `appduct mcp`
+ * from starting: the server is still fully useful for proxying an app's tools to a session that was
+ * paired some other way (a QR scan, `appduct link` in another terminal), and an MCP client that
+ * cannot start its server gets a much worse failure than one whose `appduct_connect` call
+ * returns a clear `invalid_request`. So a scheme problem here is downgraded to an extra entry in
+ * the `tried` list, which `appduct_connect` renders if and when it is actually called.
+ *
+ * It is *also* reported on stderr at startup, because an explicitly wrong `--scheme myapp://` or
+ * `APPDUCT_SCHEME` is a typo the operator wants to hear about immediately, not only if and when
+ * some agent happens to call `appduct_connect`. Stderr, never stdout: stdout carries MCP
+ * protocol frames exclusively, and MCP clients surface a server's stderr in their logs.
+ */
+const resolveSchemeForServer = async (context, configScheme, paths) => {
+    try {
+        return await resolveScheme({
+            flagScheme: context.scheme,
+            env: context.schemeEnv,
+            cwd: context.cwd,
+            configScheme,
+            stateConfigPath: paths.configPath,
+            stateDirRoot: paths.root,
+        });
+    }
+    catch (error) {
+        const message = error.message;
+        (context.stderr ?? process.stderr).write(`appduct mcp: could not resolve a deep-link scheme: ${message}\n` +
+            "The server is starting anyway; appduct_connect will fail until this is fixed.\n");
+        return { tried: [`(scheme resolution failed: ${message})`] };
+    }
+};
+export const handleMcpCommand = async (context) => {
+    const paths = getStateDirPaths(context.stateDir);
+    const config = await loadConfig(paths);
+    const { scheme, tried } = await resolveSchemeForServer(context, config.scheme, paths);
+    const handle = await createMcpServer({
+        stateDir: context.stateDir,
+        spawn: context.spawn,
+        checkVersion: context.checkVersion,
+        scheme,
+        schemeTried: tried,
+        iosBundleId: context.iosBundleId ?? config.iosBundleId,
+        exec: context.exec,
+        env: context.env,
+    });
+    let resolveCompletion;
+    const completion = new Promise((resolve) => {
+        resolveCompletion = resolve;
+    });
+    let stopped = false;
+    const stop = () => {
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        void handle.close().finally(resolveCompletion);
+    };
+    // The client disconnecting (stdin closed) ends the transport, which must end the command
+    // gracefully rather than hang forever waiting for a Ctrl-C that will never come.
+    handle.server.onclose = stop;
+    handle.server.onerror = (error) => {
+        console.error("appduct mcp: transport error:", error);
+    };
+    try {
+        await handle.connect(new StdioServerTransport(context.stdin, context.stdout));
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+    return {
+        // Never rendered: the dispatcher suppresses the bootstrap render for this command (see the
+        // doc comment above) so stdout carries only MCP protocol frames.
+        result: { ok: true, data: undefined },
+        completion,
+        stop,
+        handle,
+    };
+};

package/dist/commands/revoke.d.ts

@@ -0,0 +1,12 @@
+/** `appduct revoke` (ARCHITECTURE.md §10): revokes a session, optionally by selector. */
+import type { CliResult, RevokeCommandData } from "../cli/result-types.js";
+import { type SpawnFn } from "../rpc/client.js";
+export type RevokeCommandOptions = {
+    selector?: string;
+};
+export type RevokeCommandContext = {
+    stateDir: string;
+    spawn?: SpawnFn;
+};
+export declare const handleRevokeCommand: (options: RevokeCommandOptions, context: RevokeCommandContext) => Promise<CliResult<RevokeCommandData>>;
+//# sourceMappingURL=revoke.d.ts.map

package/dist/commands/revoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revoke.d.ts","sourceRoot":"","sources":["../../src/commands/revoke.ts"],"names":[],"mappings":"AAAA,yFAAyF;AAIzF,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE5D,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,SAAS,oBAAoB,EAC7B,SAAS,oBAAoB,KAC5B,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAQtC,CAAC"}

package/dist/commands/revoke.js

@@ -0,0 +1,7 @@
+/** `appduct revoke` (ARCHITECTURE.md §10): revokes a session, optionally by selector. */
+import { RPC_METHODS } from "@appduct/shared";
+import { callDaemon } from "../rpc/client.js";
+export const handleRevokeCommand = async (options, context) => {
+    await callDaemon(RPC_METHODS.sessionsRevoke, { selector: options.selector }, { stateDir: context.stateDir, spawn: context.spawn });
+    return { ok: true, data: { ok: true } };
+};

package/dist/commands/tools.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `appduct tools` (ARCHITECTURE.md §10): `tools [selector] [--full]` lists tools for a session;
+ * `tools [selector] <name>` shows one tool's full schema/annotations.
+ *
+ * The command table gives both forms a leading optional `[selector]`, which makes a single
+ * positional argument inherently ambiguous (is it the selector, or the tool name in `tools <name>`
+ * with the selector omitted?). This resolves it the same way a human reading the table would:
+ * first try the arg as a tool name in the implicit-selector session's registry; if no such tool
+ * exists there (or the implicit selector doesn't resolve, e.g. `ambiguous_session`), fall back to
+ * treating it as a selector and list that session's tools instead.
+ */
+import type { CliResult, ToolsCommandData } from "../cli/result-types.js";
+import { type SpawnFn } from "../rpc/client.js";
+export type ToolsCommandOptions = {
+    selector?: string;
+    name?: string;
+};
+export type ToolsCommandContext = {
+    stateDir: string;
+    spawn?: SpawnFn;
+};
+export declare const handleToolsCommand: (options: ToolsCommandOptions, context: ToolsCommandContext) => Promise<CliResult<ToolsCommandData>>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/commands/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/commands/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1E,OAAO,EAA8B,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE5E,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAiBF,eAAO,MAAM,kBAAkB,GAC7B,SAAS,mBAAmB,EAC5B,SAAS,mBAAmB,KAC3B,OAAO,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAyCrC,CAAC"}

package/dist/commands/tools.js

@@ -0,0 +1,52 @@
+/**
+ * `appduct tools` (ARCHITECTURE.md §10): `tools [selector] [--full]` lists tools for a session;
+ * `tools [selector] <name>` shows one tool's full schema/annotations.
+ *
+ * The command table gives both forms a leading optional `[selector]`, which makes a single
+ * positional argument inherently ambiguous (is it the selector, or the tool name in `tools <name>`
+ * with the selector omitted?). This resolves it the same way a human reading the table would:
+ * first try the arg as a tool name in the implicit-selector session's registry; if no such tool
+ * exists there (or the implicit selector doesn't resolve, e.g. `ambiguous_session`), fall back to
+ * treating it as a selector and list that session's tools instead.
+ */
+import { RPC_METHODS } from "@appduct/shared";
+import { usageError } from "../errors.js";
+import { callDaemon, DaemonRpcError } from "../rpc/client.js";
+const listTools = (selector, context) => {
+    return callDaemon(RPC_METHODS.toolsList, { selector }, { stateDir: context.stateDir, spawn: context.spawn });
+};
+const findTool = (tools, name) => {
+    return tools.find((tool) => tool.name === name);
+};
+export const handleToolsCommand = async (options, context) => {
+    if (options.selector !== undefined && options.name !== undefined) {
+        const tools = await listTools(options.selector, context);
+        const tool = findTool(tools, options.name);
+        if (!tool) {
+            throw usageError(`Tool "${options.name}" is not registered on session "${options.selector}".`, { available: tools.map((entry) => entry.name) });
+        }
+        return { ok: true, data: tool };
+    }
+    if (options.selector !== undefined) {
+        // A single positional arg: try it as the implicit session's tool name first.
+        let implicitTools;
+        try {
+            implicitTools = await listTools(undefined, context);
+        }
+        catch (error) {
+            if (!(error instanceof DaemonRpcError)) {
+                throw error;
+            }
+        }
+        if (implicitTools) {
+            const tool = findTool(implicitTools, options.selector);
+            if (tool) {
+                return { ok: true, data: tool };
+            }
+        }
+        // Not a tool name on the implicit session (or there is no implicit session): treat the arg as
+        // a selector and list that session's tools instead.
+        return { ok: true, data: await listTools(options.selector, context) };
+    }
+    return { ok: true, data: await listTools(undefined, context) };
+};

package/dist/daemon/address.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Advertised-address detection (ARCHITECTURE.md §2, §8 bootstrap endpoint). Prefers a
+ * non-internal private IPv4 address, falling back to IPv6, then loopback. Fixes v1's
+ * `detectHostIp`, which happily returned a Docker bridge address (`172.17.x.x`, inside the RFC
+ * 1918 172.16/12 block v1 treated as "private") — that address is unreachable from a physical
+ * device and made the printed deep link useless. Also excludes the IPv4 CGNAT range
+ * (`100.64.0.0/10`), which is routable-looking but not device-reachable in the common case.
+ */
+import { type AddressFamily } from "@appduct/shared";
+export type AdvertisedAddress = {
+    family: AddressFamily;
+    address: string;
+};
+/** Docker's default bridge network (`docker0`), the exact defect v1 shipped with. */
+export declare const isDockerDefaultBridgeAddress: (address: string) => boolean;
+/** Carrier-grade NAT shared address space (RFC 6598): `100.64.0.0/10`. */
+export declare const isCgnatIpv4Address: (address: string) => boolean;
+export declare const isExcludedIpv4Address: (address: string) => boolean;
+export type DetectAdvertisedAddressOptions = {
+    /** Explicit operator override (config or flag); skips interface enumeration entirely. */
+    override?: string;
+};
+/**
+ * Enumerates non-internal interface addresses and picks the best advertisable candidate: a
+ * private (RFC 1918) IPv4 address first (excluding Docker/CGNAT), then any other non-internal
+ * IPv4, then a unique-local (`fd00::/8`) IPv6 address, then any other non-internal, non-link-local
+ * IPv6 address, finally falling back to loopback if nothing else is available.
+ */
+export declare const detectAdvertisedAddress: (options?: DetectAdvertisedAddressOptions) => AdvertisedAddress;
+//# sourceMappingURL=address.d.ts.map

package/dist/daemon/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../../src/daemon/address.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,4BAA4B,GAAI,SAAS,MAAM,KAAG,OAE9D,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG,OAWpD,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,SAAS,MAAM,KAAG,OAEvD,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAClC,UAAS,8BAAmC,KAC3C,iBA+CF,CAAC"}

package/dist/daemon/address.js

@@ -0,0 +1,71 @@
+/**
+ * Advertised-address detection (ARCHITECTURE.md §2, §8 bootstrap endpoint). Prefers a
+ * non-internal private IPv4 address, falling back to IPv6, then loopback. Fixes v1's
+ * `detectHostIp`, which happily returned a Docker bridge address (`172.17.x.x`, inside the RFC
+ * 1918 172.16/12 block v1 treated as "private") — that address is unreachable from a physical
+ * device and made the printed deep link useless. Also excludes the IPv4 CGNAT range
+ * (`100.64.0.0/10`), which is routable-looking but not device-reachable in the common case.
+ */
+import { networkInterfaces } from "node:os";
+import { isLinkLocalIpv6Address, isPrivateIpv4Address, isUniqueLocalIpv6Address, } from "@appduct/shared";
+/** Docker's default bridge network (`docker0`), the exact defect v1 shipped with. */
+export const isDockerDefaultBridgeAddress = (address) => {
+    return address.startsWith("172.17.");
+};
+/** Carrier-grade NAT shared address space (RFC 6598): `100.64.0.0/10`. */
+export const isCgnatIpv4Address = (address) => {
+    const parts = address.split(".");
+    if (parts.length !== 4) {
+        return false;
+    }
+    const first = Number(parts[0]);
+    const second = Number(parts[1]);
+    return first === 100 && Number.isInteger(second) && second >= 64 && second <= 127;
+};
+export const isExcludedIpv4Address = (address) => {
+    return isDockerDefaultBridgeAddress(address) || isCgnatIpv4Address(address);
+};
+/**
+ * Enumerates non-internal interface addresses and picks the best advertisable candidate: a
+ * private (RFC 1918) IPv4 address first (excluding Docker/CGNAT), then any other non-internal
+ * IPv4, then a unique-local (`fd00::/8`) IPv6 address, then any other non-internal, non-link-local
+ * IPv6 address, finally falling back to loopback if nothing else is available.
+ */
+export const detectAdvertisedAddress = (options = {}) => {
+    if (options.override) {
+        return {
+            family: options.override.includes(":") ? 6 : 4,
+            address: options.override,
+        };
+    }
+    const ipv4Candidates = [];
+    const ipv6Candidates = [];
+    for (const entries of Object.values(networkInterfaces())) {
+        for (const entry of entries ?? []) {
+            if (entry.internal) {
+                continue;
+            }
+            if (entry.family === "IPv4") {
+                if (isExcludedIpv4Address(entry.address)) {
+                    continue;
+                }
+                ipv4Candidates.push(entry.address);
+            }
+            else if (entry.family === "IPv6") {
+                if (isLinkLocalIpv6Address(entry.address)) {
+                    continue;
+                }
+                ipv6Candidates.push(entry.address);
+            }
+        }
+    }
+    const preferredIpv4 = ipv4Candidates.find((address) => isPrivateIpv4Address(address)) ?? ipv4Candidates[0];
+    if (preferredIpv4) {
+        return { family: 4, address: preferredIpv4 };
+    }
+    const preferredIpv6 = ipv6Candidates.find((address) => isUniqueLocalIpv6Address(address)) ?? ipv6Candidates[0];
+    if (preferredIpv6) {
+        return { family: 6, address: preferredIpv6 };
+    }
+    return { family: 4, address: "127.0.0.1" };
+};

package/dist/daemon/audit.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Append-only per-day audit log (ARCHITECTURE.md §3, §12): one JSONL line per `tools.call`
+ * attempt (CLI and MCP alike), regardless of outcome. Raw args are **never** written — only a hex
+ * sha256 digest of their canonical JSON, so an operator can correlate repeated/identical calls
+ * without the log becoming a second copy of whatever secrets a tool's arguments carried.
+ *
+ * Writes are serialized through an internal promise queue so a slow disk never blocks the
+ * `tools.call` response path: {@link AuditLogger.record} enqueues and returns immediately. A write
+ * failure never throws back into the call path — it is logged to stderr and counted in
+ * {@link AuditLogger.failedWrites} (surfaced via `daemon.status`, ARCHITECTURE.md §12 item 4).
+ * {@link AuditLogger.flush} lets the daemon's shutdown teardown wait for the queue to drain.
+ *
+ * Retention (ARCHITECTURE.md §3): day files older than `config.auditRetentionDays` are deleted by
+ * {@link AuditLogger.prune}, which the daemon runs at startup and once a day thereafter. Pruning
+ * runs on the same queue as the writes, so it can never race an in-flight append, and its failures
+ * are counted in {@link AuditLogger.failedPrunes} and warned rather than thrown — exactly like a
+ * failed write.
+ */
+import type { ErrorType } from "@appduct/shared";
+import type { Clock } from "../cli/types.js";
+export type AuditOutcome = "ok" | "error" | "denied" | "cancelled";
+export type AuditCaller = "cli" | "mcp" | "client";
+export type AuditRecord = {
+    /** ISO 8601. */
+    ts: string;
+    sessionId: string;
+    alias: string;
+    tool: string;
+    /** Hex sha256 of the canonical JSON of the call's `args` — raw args are never logged. */
+    argsSha256: string;
+    outcome: AuditOutcome;
+    errorType?: ErrorType;
+    /**
+     * Set only when `outcome === "denied"`: `"policy"` for an ordinary `policy.*: "deny"` denial,
+     * `"no_consent_channel"` for a `"prompt"`-policy call that had no confirmed human gate
+     * (ARCHITECTURE.md §12). Without this an operator reading `audit/*.jsonl` can't tell a
+     * misconfigured `"deny"` from a `"prompt"` tool nobody has gated yet — both otherwise look like
+     * an identical `{ outcome: "denied" }` line.
+     */
+    deniedReason?: "policy" | "no_consent_channel";
+    durationMs: number;
+    caller: AuditCaller;
+    /**
+     * Set only when a `"prompt"`-policy call actually proceeded because the MCP server confirmed a
+     * consent gate (ARCHITECTURE.md §12). Deliberately distinct from a plain `"ok"`: the daemon
+     * never observed either channel's client-side behavior itself, only that the call arrived
+     * carrying this marker. The value distinguishes which gate fired:
+     * - `"client"` (issue #14): the flag-based gate — the weaker of the two, evidence only that
+     *   `_meta["anthropic/requiresUserInteraction"]` was emitted and the client is one known to
+     *   enforce it, not that a human actually answered a prompt.
+     * - `"elicitation"` (issue #10): the client replied `action: "accept"` to a live
+     *   `elicitation/create` request sent for this call — an observed decision, not merely an armed
+     *   flag, though still not independently verifiable by the daemon (see the field-level trust
+     *   caveat on `ToolsCallParams.consent` in `@appduct/shared`).
+     */
+    consent?: "client" | "elicitation";
+};
+/**
+ * Audit directory footprint, surfaced by `daemon.status` so the growth is visible (issue #32).
+ * Both fields are absent — not zero — when the directory could not be read at all; "we could not
+ * measure it" and "it is empty" are different facts and `daemon.status` reports them differently.
+ */
+export type AuditStats = {
+    /** Number of `<YYYY-MM-DD>.jsonl` day files currently on disk. */
+    files?: number;
+    /** Total bytes across those files. */
+    bytes?: number;
+};
+export type AuditPruneResult = {
+    /** Day files deleted by this run. */
+    deleted: number;
+    /** Day files this run tried and failed to delete (also added to {@link AuditLogger.failedPrunes}). */
+    failed: number;
+};
+export type AuditLogger = {
+    /** Enqueues one JSONL line for the day derived from the current clock; returns immediately
+     * (fire-and-forget from the caller's perspective — see the module doc comment). */
+    record: (entry: Omit<AuditRecord, "ts">) => void;
+    /** Count of write failures since the logger was created (never resets). */
+    failedWrites: () => number;
+    /** Count of prune failures since the logger was created (never resets). */
+    failedPrunes: () => number;
+    /**
+     * Deletes every `<YYYY-MM-DD>.jsonl` day file older than the retention window — never today's,
+     * never anything else in the directory. Runs on the write queue and never rejects: failures are
+     * counted and warned.
+     */
+    prune: () => Promise<AuditPruneResult>;
+    /** Current day-file count and total size; `{ files: 0, bytes: 0 }` when the directory does not
+     * exist yet or cannot be read. */
+    stats: () => Promise<AuditStats>;
+    /** Resolves once every queued write so far has settled (success or logged failure). */
+    flush: () => Promise<void>;
+};
+export type AuditLoggerOptions = {
+    auditDir: string;
+    clock?: Clock;
+    /** Days of history {@link AuditLogger.prune} keeps; defaults to
+     * {@link DEFAULT_AUDIT_RETENTION_DAYS}. */
+    retentionDays?: number;
+    /** Sink for write-failure diagnostics; defaults to `process.stderr`. Injectable for tests. */
+    warn?: (message: string) => void;
+};
+export declare const canonicalArgsJson: (args: Record<string, unknown>) => string;
+export declare const argsSha256: (args: Record<string, unknown>) => string;
+export declare const createAuditLogger: (options: AuditLoggerOptions) => AuditLogger;
+//# sourceMappingURL=audit.d.ts.map

package/dist/daemon/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/daemon/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAG7C,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;AACnE,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG;IACxB,gBAAgB;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,yFAAyF;IACzF,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,oBAAoB,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;CACpC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,sGAAsG;IACtG,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB;uFACmF;IACnF,MAAM,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC;IACjD,2EAA2E;IAC3E,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,YAAY,EAAE,MAAM,MAAM,CAAC;IAC3B;;;;OAIG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACvC;sCACkC;IAClC,KAAK,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IACjC,uFAAuF;IACvF,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;+CAC2C;IAC3C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8FAA8F;IAC9F,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC,CAAC;AAiBF,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAEjE,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAE1D,CAAC;AA8DF,eAAO,MAAM,iBAAiB,GAAI,SAAS,kBAAkB,KAAG,WA4K/D,CAAC"}

package/dist/daemon/audit.js

@@ -0,0 +1,237 @@
+/**
+ * Append-only per-day audit log (ARCHITECTURE.md §3, §12): one JSONL line per `tools.call`
+ * attempt (CLI and MCP alike), regardless of outcome. Raw args are **never** written — only a hex
+ * sha256 digest of their canonical JSON, so an operator can correlate repeated/identical calls
+ * without the log becoming a second copy of whatever secrets a tool's arguments carried.
+ *
+ * Writes are serialized through an internal promise queue so a slow disk never blocks the
+ * `tools.call` response path: {@link AuditLogger.record} enqueues and returns immediately. A write
+ * failure never throws back into the call path — it is logged to stderr and counted in
+ * {@link AuditLogger.failedWrites} (surfaced via `daemon.status`, ARCHITECTURE.md §12 item 4).
+ * {@link AuditLogger.flush} lets the daemon's shutdown teardown wait for the queue to drain.
+ *
+ * Retention (ARCHITECTURE.md §3): day files older than `config.auditRetentionDays` are deleted by
+ * {@link AuditLogger.prune}, which the daemon runs at startup and once a day thereafter. Pruning
+ * runs on the same queue as the writes, so it can never race an in-flight append, and its failures
+ * are counted in {@link AuditLogger.failedPrunes} and warned rather than thrown — exactly like a
+ * failed write.
+ */
+import { createHash } from "node:crypto";
+import { chmod, mkdir, open, readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { DEFAULT_AUDIT_RETENTION_DAYS } from "./config.js";
+/** Recursively sorts object keys so semantically-identical args always hash identically,
+ * regardless of the property insertion order the caller happened to use. */
+const canonicalize = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return Object.fromEntries(Object.keys(record).sort().map((key) => [key, canonicalize(record[key])]));
+    }
+    return value;
+};
+export const canonicalArgsJson = (args) => {
+    return JSON.stringify(canonicalize(args));
+};
+export const argsSha256 = (args) => {
+    return createHash("sha256").update(canonicalArgsJson(args)).digest("hex");
+};
+/** The UTC day stamp a record written at `date` lands in. UTC (not local time) because that is
+ * exactly what the file names have always been derived from — see {@link auditFilePathForDate}. */
+const dayStamp = (date) => {
+    return date.toISOString().slice(0, 10); // YYYY-MM-DD
+};
+/** Matches only the day files this module writes. Anything else in `audit/` — an operator's
+ * notes, a partial copy, a subdirectory — is never a pruning candidate. */
+const AUDIT_DAY_FILE = /^(\d{4}-\d{2}-\d{2})\.jsonl$/u;
+/** The captured day stamp when `name` is one of our day files *and* the stamp is a real calendar
+ * date (so a plausible-looking `2026-13-45.jsonl` is left alone rather than compared as a string). */
+const dayStampOfAuditFile = (name) => {
+    const match = AUDIT_DAY_FILE.exec(name);
+    if (!match) {
+        return undefined;
+    }
+    const stamp = match[1];
+    const parsed = new Date(`${stamp}T00:00:00.000Z`);
+    return Number.isNaN(parsed.getTime()) || dayStamp(parsed) !== stamp ? undefined : stamp;
+};
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * The oldest day stamp retention keeps: `retentionDays` UTC days before the day containing `now`.
+ * A day file is pruned when its stamp sorts strictly before this (ISO stamps are zero-padded, so
+ * lexicographic order is chronological order), i.e. once it is *more* than `retentionDays` days
+ * behind today. Today's file therefore can never be a candidate for any `retentionDays >= 1`.
+ */
+const oldestRetainedStamp = (now, retentionDays) => {
+    const todayUtcMidnight = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    const cutoff = new Date(todayUtcMidnight - retentionDays * MS_PER_DAY);
+    // `auditRetentionDays` is validated as a positive integer, not a *small* one: a window wide
+    // enough to run off the end of the `Date` range would make `toISOString` throw. That config
+    // means "keep everything", so answer with a stamp no real day file can sort before.
+    return Number.isNaN(cutoff.getTime()) ? "0000-00-00" : dayStamp(cutoff);
+};
+const auditFilePathForDate = (auditDir, date) => {
+    return join(auditDir, `${dayStamp(date)}.jsonl`);
+};
+const appendLine = async (filePath, line) => {
+    const handle = await open(filePath, "a", 0o600);
+    try {
+        await handle.appendFile(line);
+        // `open`'s mode only applies at creation and is further subject to umask; chmod explicitly so
+        // an existing (or umask-widened) file always ends up at the ARCHITECTURE.md §3 mode.
+        await chmod(filePath, 0o600);
+    }
+    finally {
+        await handle.close();
+    }
+};
+export const createAuditLogger = (options) => {
+    const clock = options.clock ?? { now: () => new Date() };
+    const warn = options.warn ??
+        ((message) => {
+            process.stderr.write(`${message}\n`);
+        });
+    const retentionDays = options.retentionDays ?? DEFAULT_AUDIT_RETENTION_DAYS;
+    let failedWrites = 0;
+    let failedPrunes = 0;
+    let queue = Promise.resolve();
+    /**
+     * Lists the day files in the audit directory. A *missing* directory is genuinely empty — the
+     * daemon creates it lazily — and reports `failed: false`. Any other error (EACCES on a
+     * tightened-up directory, ENOTDIR where a file now sits, EIO on a failing disk) is a refusal to
+     * answer, not an answer of zero, and is reported as such: callers must not turn "we could not
+     * look" into "there is nothing there".
+     */
+    const listDayFiles = async () => {
+        let entries;
+        try {
+            entries = await readdir(options.auditDir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return { files: [], failed: false };
+            }
+            return { files: [], failed: true, error: error };
+        }
+        const files = [];
+        for (const entry of entries) {
+            if (!entry.isFile()) {
+                continue;
+            }
+            const stamp = dayStampOfAuditFile(entry.name);
+            if (stamp !== undefined) {
+                files.push({ name: entry.name, stamp });
+            }
+        }
+        return { files, failed: false };
+    };
+    const pruneOnce = async () => {
+        const today = dayStamp(clock.now());
+        const cutoff = oldestRetainedStamp(clock.now(), retentionDays);
+        let deleted = 0;
+        let failed = 0;
+        const listing = await listDayFiles();
+        if (listing.failed) {
+            // A sweep that could not read the directory did not prune anything and cannot know whether
+            // it needed to — counted and warned like any other prune failure, so a permanently
+            // unreadable `audit/` shows up in `daemon.status` instead of looking like a tidy one.
+            failedPrunes += 1;
+            warn(`appduct daemon: failed to read the audit directory to prune it: ${listing.error?.message}`);
+            return { deleted: 0, failed: 1 };
+        }
+        for (const file of listing.files) {
+            // Belt and braces: `cutoff` is already strictly behind `today` for every valid
+            // `retentionDays`, but today's file is the one file that must never disappear from under an
+            // open append, so it is excluded explicitly (issue #32).
+            if (file.stamp === today || file.stamp >= cutoff) {
+                continue;
+            }
+            try {
+                await rm(join(options.auditDir, file.name), { force: true });
+                deleted += 1;
+            }
+            catch (error) {
+                failed += 1;
+                failedPrunes += 1;
+                warn(`appduct daemon: failed to prune the audit record "${file.name}": ${error.message}`);
+            }
+        }
+        return { deleted, failed };
+    };
+    const record = (entry) => {
+        const now = clock.now();
+        const full = { ts: now.toISOString(), ...entry };
+        const line = `${JSON.stringify(full)}\n`;
+        const filePath = auditFilePathForDate(options.auditDir, now);
+        // Chained onto the existing queue tail so writes for the same (or different) day never race
+        // each other; a failure is swallowed here (never rejects the chain) so one bad write can't
+        // poison every audit record after it.
+        queue = queue.then(async () => {
+            try {
+                await mkdir(options.auditDir, { recursive: true });
+                await appendLine(filePath, line);
+            }
+            catch (error) {
+                failedWrites += 1;
+                warn(`appduct daemon: failed to write an audit record: ${error.message}`);
+            }
+        });
+    };
+    /**
+     * Chained onto the write queue for the same reason the writes are chained onto each other: a
+     * prune must never interleave with the append it would otherwise delete out from under. The
+     * returned promise resolves with this prune's own result while the queue itself stays a
+     * never-rejecting `Promise<void>` that `flush` can keep awaiting.
+     */
+    const prune = () => {
+        let settle;
+        const result = new Promise((resolve) => {
+            settle = resolve;
+        });
+        queue = queue.then(async () => {
+            try {
+                settle(await pruneOnce());
+            }
+            catch (error) {
+                // `pruneOnce` handles per-file failures itself; this only catches a failure of the listing
+                // step, which must still never reject the queue.
+                failedPrunes += 1;
+                warn(`appduct daemon: failed to prune the audit log: ${error.message}`);
+                settle({ deleted: 0, failed: 1 });
+            }
+        });
+        return result;
+    };
+    const stats = async () => {
+        const listing = await listDayFiles();
+        if (listing.failed) {
+            // Reported as "not measured", never as an empty directory: `daemon.status` would otherwise
+            // tell an operator that `audit/` holds nothing at exactly the moment it has become
+            // unreadable — the moment they most need to know otherwise.
+            return {};
+        }
+        let files = 0;
+        let bytes = 0;
+        for (const file of listing.files) {
+            try {
+                bytes += (await stat(join(options.auditDir, file.name))).size;
+                files += 1;
+            }
+            catch {
+                // Raced with a prune (ours or an operator's `rm`); an audit record that is gone by the
+                // time it is measured simply does not count toward the reported footprint.
+            }
+        }
+        return { files, bytes };
+    };
+    return {
+        record,
+        failedWrites: () => failedWrites,
+        failedPrunes: () => failedPrunes,
+        prune,
+        stats,
+        flush: () => queue,
+    };
+};