@aragon-agent/tui 0.0.0-stage → 0.0.1

package/dist/model/logging/levels.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Log levels — the ordering, the names, and the two coercion helpers.
+ *
+ * Kept in its own module because it is the one piece of the logging subsystem
+ * the config layer (`schema.ts`) and the settings screen need, and neither
+ * should have to pull in a file sink to learn what "debug" is called.
+ *
+ * PRIVACY IS PART OF THE LADDER, not a side effect of it:
+ *
+ *   error  crashes, failed requests, config write/parse failures
+ *   warn   degraded migrations, clamped values, dropped records
+ *   info   lifecycle, config writes, turn boundaries + token counts, tool
+ *          names and durations — NO conversation content at all
+ *   debug  the above plus prompts / replies / tool args truncated to
+ *          `previewChars`
+ *   trace  full message bodies, full tool arguments and output
+ *
+ * `info` is the default precisely so that "send me your log" is a safe thing to
+ * ask a user. `debug` and above are not, and the README says so.
+ */
+export declare const LOG_LEVELS: {
+    readonly silent: 0;
+    readonly error: 10;
+    readonly warn: 20;
+    readonly info: 30;
+    readonly debug: 40;
+    readonly trace: 50;
+};
+export type LogLevelName = keyof typeof LOG_LEVELS;
+export declare const LOG_LEVEL_NAMES: readonly LogLevelName[];
+export declare function isLogLevel(v: unknown): v is LogLevelName;
+/**
+ * Coerce anything into a level, falling back rather than throwing.
+ *
+ * Same discipline as `clampTheme` / `clampThinkingLevel`: a nonsense value in
+ * the config file must not stop the CLI from starting.
+ */
+export declare function clampLogLevel(v: unknown, fallback: LogLevelName): LogLevelName;
+/** True when a record at `level` should be emitted under `threshold`. */
+export declare function isLevelEnabled(level: LogLevelName, threshold: LogLevelName): boolean;

package/dist/model/logging/levels.js

@@ -0,0 +1,59 @@
+/**
+ * Log levels — the ordering, the names, and the two coercion helpers.
+ *
+ * Kept in its own module because it is the one piece of the logging subsystem
+ * the config layer (`schema.ts`) and the settings screen need, and neither
+ * should have to pull in a file sink to learn what "debug" is called.
+ *
+ * PRIVACY IS PART OF THE LADDER, not a side effect of it:
+ *
+ *   error  crashes, failed requests, config write/parse failures
+ *   warn   degraded migrations, clamped values, dropped records
+ *   info   lifecycle, config writes, turn boundaries + token counts, tool
+ *          names and durations — NO conversation content at all
+ *   debug  the above plus prompts / replies / tool args truncated to
+ *          `previewChars`
+ *   trace  full message bodies, full tool arguments and output
+ *
+ * `info` is the default precisely so that "send me your log" is a safe thing to
+ * ask a user. `debug` and above are not, and the README says so.
+ */
+export const LOG_LEVELS = {
+    silent: 0,
+    error: 10,
+    warn: 20,
+    info: 30,
+    debug: 40,
+    trace: 50,
+};
+export const LOG_LEVEL_NAMES = [
+    'silent',
+    'error',
+    'warn',
+    'info',
+    'debug',
+    'trace',
+];
+export function isLogLevel(v) {
+    return typeof v === 'string' && Object.prototype.hasOwnProperty.call(LOG_LEVELS, v);
+}
+/**
+ * Coerce anything into a level, falling back rather than throwing.
+ *
+ * Same discipline as `clampTheme` / `clampThinkingLevel`: a nonsense value in
+ * the config file must not stop the CLI from starting.
+ */
+export function clampLogLevel(v, fallback) {
+    if (isLogLevel(v))
+        return v;
+    if (typeof v === 'string' && isLogLevel(v.trim().toLowerCase())) {
+        return v.trim().toLowerCase();
+    }
+    return fallback;
+}
+/** True when a record at `level` should be emitted under `threshold`. */
+export function isLevelEnabled(level, threshold) {
+    if (threshold === 'silent')
+        return false;
+    return LOG_LEVELS[level] <= LOG_LEVELS[threshold];
+}

package/dist/model/logging/log-port.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The logging PORT the terminal-UI code writes to (tui-package-split S1 / D10).
+ *
+ * WHY A PORT AND NOT THE LOGGER. The process-wide `Logger` (file sink, redaction, session
+ * id, the four process hooks) is infrastructure that belongs to the executable, not to the
+ * terminal runtime. Four view-model / renderer modules used to call `getLogger()`
+ * directly; once those modules live in their own package they must not reach back into
+ * the CLI to do it. They call `getTuiLogger()` instead, with the SAME arguments, and the
+ * CLI connects the real logger when `logging/logger.ts` is loaded (see the bottom of that file).
+ *
+ * THE DEFAULT IS A NO-OP, AND THAT IS DELIBERATE: a consumer that never installs a
+ * logger (the package's own tests, an embedder) gets silence rather than a crash or a
+ * stray file. `getTuiLogger()` NEVER returns `undefined`, so a call site needs no guard.
+ *
+ * `TuiLogScope` must stay a SUBSET of the CLI's `LogScope`: that is what lets the CLI's
+ * `Logger` be assigned to this port with no cast. The compiler enforces it at the single
+ * wiring site at the bottom of `logger.ts`; widening this union without widening `LogScope` there is a
+ * compile error, not a silently dropped record.
+ */
+export type TuiLogScope = 'cli' | 'config' | 'compaction' | 'llm';
+export type TuiLogData = Record<string, unknown>;
+export interface TuiScopedLogger {
+    error(msg: string, data?: TuiLogData): void;
+    warn(msg: string, data?: TuiLogData): void;
+    info(msg: string, data?: TuiLogData): void;
+    debug(msg: string, data?: TuiLogData): void;
+}
+export interface TuiLogger {
+    error(scope: TuiLogScope, msg: string, data?: TuiLogData): void;
+    warn(scope: TuiLogScope, msg: string, data?: TuiLogData): void;
+    info(scope: TuiLogScope, msg: string, data?: TuiLogData): void;
+    debug(scope: TuiLogScope, msg: string, data?: TuiLogData): void;
+    child(scope: TuiLogScope): TuiScopedLogger;
+}
+/** Installs the real logger; `null` restores the no-op default (tests, teardown). */
+export declare function setTuiLogger(logger: TuiLogger | null): void;
+/** Never `undefined`: the default is a no-op, so call sites need no guard. */
+export declare function getTuiLogger(): TuiLogger;

package/dist/model/logging/log-port.js

@@ -0,0 +1,41 @@
+/**
+ * The logging PORT the terminal-UI code writes to (tui-package-split S1 / D10).
+ *
+ * WHY A PORT AND NOT THE LOGGER. The process-wide `Logger` (file sink, redaction, session
+ * id, the four process hooks) is infrastructure that belongs to the executable, not to the
+ * terminal runtime. Four view-model / renderer modules used to call `getLogger()`
+ * directly; once those modules live in their own package they must not reach back into
+ * the CLI to do it. They call `getTuiLogger()` instead, with the SAME arguments, and the
+ * CLI connects the real logger when `logging/logger.ts` is loaded (see the bottom of that file).
+ *
+ * THE DEFAULT IS A NO-OP, AND THAT IS DELIBERATE: a consumer that never installs a
+ * logger (the package's own tests, an embedder) gets silence rather than a crash or a
+ * stray file. `getTuiLogger()` NEVER returns `undefined`, so a call site needs no guard.
+ *
+ * `TuiLogScope` must stay a SUBSET of the CLI's `LogScope`: that is what lets the CLI's
+ * `Logger` be assigned to this port with no cast. The compiler enforces it at the single
+ * wiring site at the bottom of `logger.ts`; widening this union without widening `LogScope` there is a
+ * compile error, not a silently dropped record.
+ */
+const NOOP_SCOPED = {
+    error: () => { },
+    warn: () => { },
+    info: () => { },
+    debug: () => { },
+};
+const NOOP_LOGGER = {
+    error: () => { },
+    warn: () => { },
+    info: () => { },
+    debug: () => { },
+    child: () => NOOP_SCOPED,
+};
+let installed = null;
+/** Installs the real logger; `null` restores the no-op default (tests, teardown). */
+export function setTuiLogger(logger) {
+    installed = logger;
+}
+/** Never `undefined`: the default is a no-op, so call sites need no guard. */
+export function getTuiLogger() {
+    return installed ?? NOOP_LOGGER;
+}

package/dist/model/logging/secret-registry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The live set of secret literals the redactor must never let reach disk.
+ *
+ * WHY A REGISTRY AND NOT A SNAPSHOT (aragon-home-config-and-logging P0-3):
+ *
+ * The format regexes in `redact.ts` catch the three vendors we know about. This
+ * registry is the backstop for everything else — a custom endpoint whose key
+ * looks like nothing in particular. That backstop only works if it holds the
+ * keys we ACTUALLY have, which is a moving target: `installLogging()` runs
+ * before commander has parsed `--api-key`, and a key the user types into the
+ * settings screen mid-session arrives later still. A set captured at startup
+ * would miss the single most common path by which a key enters the process, and
+ * would miss it silently, because the vendor regexes happen to cover the keys
+ * we test with.
+ *
+ * Process-lifetime, append-only, never serialised, never written anywhere.
+ */
+export declare function registerSecret(value: string | undefined | null): void;
+/** Convenience for the `apiKeys` maps every registration site happens to hold. */
+export declare function registerSecretsFrom(keys: Record<string, string | null | undefined> | undefined): void;
+/** Register dedicated credentials in untrusted parsed config before schema validation. */
+export declare function registerProfileSecrets(value: unknown): void;
+/**
+ * Every known secret, LONGEST FIRST.
+ *
+ * Order matters: when one key is a prefix of another, replacing the short one
+ * first leaves the remainder of the long one in the file — a partial key is
+ * still a leak, and a more convincing one for being partial.
+ */
+export declare function getSecrets(): readonly string[];
+/** Tests only. Production code has no reason to forget a secret. */
+export declare function clearSecretsForTest(): void;

package/dist/model/logging/secret-registry.js

@@ -0,0 +1,73 @@
+/**
+ * The live set of secret literals the redactor must never let reach disk.
+ *
+ * WHY A REGISTRY AND NOT A SNAPSHOT (aragon-home-config-and-logging P0-3):
+ *
+ * The format regexes in `redact.ts` catch the three vendors we know about. This
+ * registry is the backstop for everything else — a custom endpoint whose key
+ * looks like nothing in particular. That backstop only works if it holds the
+ * keys we ACTUALLY have, which is a moving target: `installLogging()` runs
+ * before commander has parsed `--api-key`, and a key the user types into the
+ * settings screen mid-session arrives later still. A set captured at startup
+ * would miss the single most common path by which a key enters the process, and
+ * would miss it silently, because the vendor regexes happen to cover the keys
+ * we test with.
+ *
+ * Process-lifetime, append-only, never serialised, never written anywhere.
+ */
+const secrets = new Set();
+/**
+ * Minimum length for a value to count as a secret.
+ *
+ * Registering `"1"` or `"off"` would blank out every occurrence of that
+ * substring in ordinary log text, which destroys the log's usefulness while
+ * protecting nothing.
+ */
+const MIN_SECRET_LENGTH = 8;
+export function registerSecret(value) {
+    if (typeof value !== 'string')
+        return;
+    const trimmed = value.trim();
+    if (trimmed.length < MIN_SECRET_LENGTH)
+        return;
+    secrets.add(trimmed);
+}
+/** Convenience for the `apiKeys` maps every registration site happens to hold. */
+export function registerSecretsFrom(keys) {
+    if (!keys)
+        return;
+    for (const value of Object.values(keys))
+        registerSecret(value);
+}
+/** Register dedicated credentials in untrusted parsed config before schema validation. */
+export function registerProfileSecrets(value) {
+    if (!value || typeof value !== 'object')
+        return;
+    const profiles = value.modelProfiles;
+    if (!profiles || typeof profiles !== 'object')
+        return;
+    const entries = profiles.entries;
+    if (!Array.isArray(entries))
+        return;
+    for (const entry of entries) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const key = entry.apiKey;
+        if (typeof key === 'string')
+            registerSecret(key);
+    }
+}
+/**
+ * Every known secret, LONGEST FIRST.
+ *
+ * Order matters: when one key is a prefix of another, replacing the short one
+ * first leaves the remainder of the long one in the file — a partial key is
+ * still a leak, and a more convincing one for being partial.
+ */
+export function getSecrets() {
+    return [...secrets].sort((a, b) => b.length - a.length);
+}
+/** Tests only. Production code has no reason to forget a secret. */
+export function clearSecretsForTest() {
+    secrets.clear();
+}

package/dist/model/proc/limits.d.ts

@@ -0,0 +1,214 @@
+/**
+ * PROC_LIMITS — the single authority on every structural bound the process
+ * supervisor enforces (background-service-supervision §6).
+ *
+ * ASCII ONLY: `src/proc/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`), whose hardcoded directory regex this feature
+ * extends. A NEW TREE IS INVISIBLE TO THAT SCAN UNTIL IT IS NAMED THERE, and a
+ * guard rail that silently stops guarding is worse than no guard rail — this
+ * package has now paid for that edit eleven times.
+ *
+ * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE — the distinction
+ * `TODO_LIMITS` and `TEAM_LIMITS` each record at length:
+ *
+ *  - Everything below is STRUCTURAL: how many rows a tail can physically carry,
+ *    how many children one session may hold, how long a kill may take before it
+ *    stops being a kill. A user has no business tuning them, so they are
+ *    constants.
+ *  - The four `bash.*` config keys (`config/schema.ts`) are POLICY: register the
+ *    tools at all, let the classifier fire, how long a launch may block the
+ *    turn, how long to wait for readiness. They are clamped, persisted and
+ *    user-facing.
+ */
+export declare const PROC_LIMITS: {
+    /**
+     * Rows the per-service ring retains.
+     *
+     * DELIBERATELY A DIFFERENT NUMBER FROM `cardTailRows` BELOW, and from
+     * `LIVE_TAIL_ROWS` (8) in `tools/tool-output-store.ts`. They bound unrelated
+     * things — what `bash_output` can page back through, versus what one card
+     * draws — and a shared literal is how a later edit collapses two bounds into
+     * one.
+     */
+    readonly serviceTailRows: 200;
+    /** Rows a snapshot (and therefore a card) carries. */
+    readonly cardTailRows: 8;
+    /**
+     * JOB RECORDS one session may hold — services AND tasks share the number.
+     *
+     * NAMED `maxJobs`, NOT `maxServices` (long-task-jobs D-7). A constant that
+     * counts two kinds of job while being called `maxServices` is the next edit's
+     * bug: the limit and its refusal message would go on saying "service" while
+     * the model is holding a training run.
+     *
+     * Eviction only ever removes a record in a TERMINAL state
+     * (`exited | failed | stopped`). When all 16 are live `start()` refuses and
+     * names the oldest ids rather than evicting: evicting a live record would
+     * orphan a running server that nothing can any longer name or stop.
+     */
+    readonly maxJobs: 16;
+    /**
+     * How long `bash` waits after `'exit'` for the stdio streams to close before
+     * settling anyway.
+     *
+     * This number IS defence 1. `'close'` fires only once every stream is closed,
+     * and a detached grandchild that inherited the pipe keeps it open after the
+     * shell is long gone — so a tool that settles on `'close'` alone has a path
+     * that never settles at all.
+     *
+     * IT IS A BOUND, NOT A VERDICT. Expiry says "stop waiting"; it does NOT say
+     * the pipe was held, and the note is only printed when the streams are
+     * observed still open at that moment (`proc/output-streams.ts` records the
+     * release-gate failure a timer-based verdict caused). The ordinary path does
+     * not even reach this bound: two ended streams after `'exit'` settle the call
+     * with the byte-identical body, one notification earlier.
+     */
+    readonly drainMs: 250;
+    /**
+     * How long an aborted/timed-out `bash` waits after the kill before settling
+     * WHETHER OR NOT the child ever reported exit.
+     *
+     * A pending promise after an abort is the bug; a possibly-premature result is
+     * not.
+     */
+    readonly killGraceMs: 2000;
+    /** Readiness port probe interval. */
+    readonly probeIntervalMs: 500;
+    /** Socket timeout for one readiness probe. */
+    readonly probeSocketTimeoutMs: 1000;
+    /**
+     * Output-event coalescing window inside the supervisor.
+     *
+     * At the SOURCE rather than in the view, because the same event is also
+     * consumed by `/bg` and by `bash_output`. A webpack build emitting thousands
+     * of lines a second must not become thousands of React renders.
+     */
+    readonly outputCoalesceMs: 100;
+    /** `SIGTERM` -> `SIGKILL` escalation window for a graceful stop. */
+    readonly stopGraceMs: 3000;
+    /**
+     * How long to KEEP ASKING whether the `SIGKILL` actually landed before
+     * declaring the job `stopped`.
+     *
+     * THIS NUMBER IS NOT A GUESS ABOUT THE PLATFORM. `killTree` spawns `taskkill`,
+     * which is a process of its own: a Windows tree kill of a shell plus its node
+     * child measures ~0.8 s on the reference machine (while starting `cmd` costs
+     * 50 ms), so the fixed 250 ms this used to allow expired first and `stop()`
+     * reported `stopped` with the child still running - AC-18 caught exactly that.
+     * The wait stays BOUNDED against the opposite failure (a promise that never
+     * resolves); at this deadline the record keeps the honest `killIncomplete`
+     * flag instead.
+     */
+    readonly killVerifyMs: 2000;
+    /** Liveness poll interval while waiting for a `SIGKILL` to land. */
+    readonly killVerifyPollMs: 50;
+    /**
+     * How long ONE synchronous tree kill (`killTreeSync`) may take.
+     *
+     * MEASURED, NOT GUESSED. A `taskkill /pid <shell> /t /f` of a shell plus its
+     * node child takes 1027-1058 ms on the reference machine on an IDLE host (five
+     * samples, 2026-10-23), so the old 2000 ms was 1.9x the honest cost and the
+     * 2026-10-23 release run - where the whole suite took 340 s against the usual
+     * 200-240 s - is comfortably inside the range where a single tree kill exceeds
+     * it. Crossing it is not a slow kill, it is NO kill: `spawnSync` kills
+     * `taskkill` itself at the deadline and the tree keeps running (verified: a
+     * 150 ms budget left the child alive 1.5 s later, `ETIMEDOUT` / `status null`).
+     *
+     * 5000 ms is ~5x the measured cost. It is a CEILING and not a cost: a tree that
+     * dies in the usual second still returns in that second. The worst case is
+     * `maxJobs` (16) trees at the ceiling on an exit hook, which is why this is not
+     * any larger - the reaper prefers a reported miss to an exit that never ends,
+     * and the miss is now reported (`ProcRecord.killIncomplete`).
+     */
+    readonly killTreeSyncTimeoutMs: 5000;
+    /** Below this many terminal columns the status chip degrades to `[N]`. */
+    readonly statusCompactCols: 92;
+    /**
+     * Rows of new output one `job_wait` result carries, in addition to its status,
+     * progress, cursor, `[note]`/`[stalled]` and `[next]` lines.
+     *
+     * THE NUMBER IS THE FEATURE. One wait must cost ~150 tokens, not the ~6k a
+     * 200-row tail costs - that economy is the whole reason `job_wait` exists
+     * instead of a seventh `bash_output` poll.
+     */
+    readonly waitTailRows: 6;
+    /**
+     * Seconds a single wait may block, as a STRUCTURAL floor and ceiling (`jobs.waitSeconds` is clamped into this range).
+     *
+     * THE ONE AUTHORITY FOR THE CEILING (extended-job-wait I-2): the executor
+     * override (`JOB_WAIT_TOOL_CEILING_MS`), `WAIT_SECONDS_RANGE.max`, the tool
+     * description and the prompt block all derive from, or are asserted equal to,
+     * `waitMaxSeconds`. Changing it here and missing another reader is how a wait
+     * is silently cut short by a layer nobody remembered.
+     */
+    readonly waitMinSeconds: 5;
+    readonly waitMaxSeconds: 1200;
+    /**
+     * Cadence of the in-wait heartbeat, in ms.
+     *
+     * ONE HZ because the reader needs "a few seconds ago" precision, not a stream:
+     * subscribing to the supervisor's 100 ms output coalescing would mean ~12000
+     * pointless view updates across a 20-minute wait. The same beat also carries the
+     * wall-clock deadline re-check (see `proc/wait.ts`).
+     */
+    readonly waitHeartbeatMs: 1000;
+    /**
+     * Characters one extracted progress line may occupy.
+     *
+     * Also the width the card's progress row is assumed to take, which is why
+     * `ui/layout/virtual-window.ts` can count it as exactly one row.
+     */
+    readonly waitProgressChars: 80;
+    /**
+     * Rows `extractProgress` scans, from the tail, before giving up.
+     *
+     * Eight because a tqdm bar plus its ETA plus the loss line above it is the
+     * realistic worst case, and because a wider window is how a stale `100%` from
+     * an earlier phase wins over the live one.
+     */
+    readonly progressScanRows: 8;
+    /** Notices one `<job_notices>` block may render. Bounded so the block stays ~8 lines. */
+    readonly maxNotices: 8;
+    /** Log rows a failed job's notice carries. Two: the message and the frame above it. */
+    readonly noticeTailRows: 2;
+    /** Rows `job_list` prints before it collapses the rest into `+N more`. */
+    readonly listRows: 8;
+    /**
+     * Consecutive waits with no new row and no progress change before the
+     * `[guard]` line is prepended (R-3).
+     *
+     * A HINT, NEVER A REFUSAL: the seventh wait still waits. Refusing would take
+     * the decision away from the model at exactly the point where it has the most
+     * context.
+     */
+    readonly maxConsecutiveWaits: 6;
+    /** Bytes one mirrored job log may occupy before it stops appending. */
+    readonly logMirrorMaxBytes: 2000000;
+    /** Coalescing window for the log mirror's appends (<=4 writes/second). */
+    readonly mirrorFlushMs: 250;
+    /** Session directories the mirror keeps, newest by mtime. */
+    readonly mirrorRetainDirs: 5;
+};
+/**
+ * Bumped whenever the wording of the `<background_services>` block changes, so a
+ * behaviour report can be tied to a block revision with one grep.
+ */
+export declare const BACKGROUND_SERVICES_BLOCK_VERSION = "v1";
+/**
+ * The same discipline for the `<background_jobs>` block. A SEPARATE CONSTANT,
+ * not a bump of the one above: the two blocks are spliced by different flags
+ * (`bash.background` and `jobs.enabled`), so one version number covering both
+ * would make "which block changed" unanswerable from a report.
+ */
+export declare const JOBS_BLOCK_VERSION = "v2-2026-10";
+/**
+ * Head-room the executor's own `job_wait` timer leaves above the longest wait.
+ *
+ * It is a SECOND, INDEPENDENT clock, not a coupling to `toolTimeoutMs`
+ * (extended-job-wait I-4'): the idle watchdog is paused for the whole wait, so
+ * when `waitForJob` itself misbehaves this is the only thing left that can end
+ * the call. `toolTimeoutMs` no longer constrains a wait at all.
+ */
+export declare const JOB_WAIT_MARGIN_MS = 30000;
+/** The executor ceiling for `job_wait`: the longest wait plus its margin (1230 s). */
+export declare const JOB_WAIT_TOOL_CEILING_MS: number;