@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/core/memory/secret-scanner.js

@@ -0,0 +1,304 @@
+/**
+ * Persona-memory secret scanner (backlog,  hardening).
+ *
+ * Defense against API keys / credentials accidentally landing in shared
+ * persona memory. A naive operator typing `pugi memory write fact "Use
+ * API key sk-ant-..."` would silently persist that secret to the
+ * `the platform database.persona_memory` table — visible to every persona, every
+ * recall query, every dual-write sink. This module is the chokepoint
+ * that refuses such writes.
+ *
+ * # Scope
+ *
+ * Scoped to the persona-memory write surface (`pugi memory write` and
+ * the `pugi remember` curator's `defaultPersist`). NOT a global secret
+ * scanner — the tarball pre-publish gate
+ * (`apps/pugi-cli/scripts/secret-scanner.mjs`) covers npm publish, and
+ * gitleaks covers git history. The two scanners share the pattern
+ * vocabulary but live at different boundaries; do NOT consolidate
+ * without re-validating each call site.
+ *
+ * # Patterns shipped
+ *
+ *  1. Anthropic key           sk-ant-…             high
+ *  2. Generic OpenAI-style    sk-…                 high
+ *  3. GitHub PAT / installation tokens (ghp_/ghs_/gho_/ghu_)
+ *                                                      high
+ *  4. AWS access key id       AKIA…                high
+ *  5. Plane API token         plane_api_…          high   [pugi-leak-ok]
+ *  6. npm token               npm_…                high
+ *  7. Slack token             xox[bpoars]-…        high
+ *  8. Stripe secret key       sk_(live|test)_…     high
+ *  9. JWT-shaped token        eyJ…\.…\.…           medium
+ * 10. Generic Bearer header   Bearer <opaque>      medium
+ * 11. Private-key PEM header  -----BEGIN … PRIVATE… high
+ * 12. Pugi internal Anvil key anvil_… / sk_anvil_… high
+ *
+ * Each rule names its pattern; matches are surfaced by `pattern` name
+ * so the operator can map the rejection back to a credential type.
+ *
+ * # Confidence levels
+ *
+ * `high` — the regex is prefix-anchored to a vendor-issued shape that
+ * is rare in normal English text (e.g. `sk-ant-`, `AKIA`, `ghp_`). A
+ * single match is enough to reject.
+ *
+ * `medium` — the regex is structural (JWT, Bearer, hex blob). False
+ * positives ARE possible. Default behaviour rejects on medium matches
+ * too (security-first), but operators can downgrade to high-only via
+ * the `PUGI_MEMORY_SECRET_STRICT=0` opt-out — see `scanForSecrets`'s
+ * `strict` option.
+ *
+ * # Opt-outs
+ *
+ *  - `PUGI_MEMORY_SECRET_SCAN_DISABLE=1`  bypass entirely (tests).
+ *  - `PUGI_MEMORY_SECRET_STRICT=0`        ignore medium-confidence
+ *                                           matches (still rejects
+ *                                           on high).
+ *  - `--allow-redacted` flag (handled by caller) opts into auto-redact
+ *    instead of reject. The scanner exposes `redactSecrets` for that
+ *    caller — see `runtime/commands/memory.ts`.
+ *
+ * # independent implementation provenance
+ *
+ * Inspired by the the upstream tool teamMemorySync.secretScanner pattern
+ * (intel from leak-research memos). independent implementation TypeScript
+ * implementation — no upstream code reused. Pattern vocabulary was
+ * cross-referenced against the existing
+ * `apps/pugi-cli/scripts/secret-scanner.mjs` tarball gate so a single
+ * vendor (AWS, GitHub, etc.) is handled the same way in both surfaces.
+ */
+/**
+ * Pattern registry. Each regex is anchored with a non-capturing
+ * boundary and uses bounded quantifiers — no `.*` and no nested
+ * alternations that would invite catastrophic backtracking.
+ *
+ * NOTE: regexes are constructed with the `g` flag here because
+ * `String.prototype.matchAll` requires it. The scanner clones each
+ * regex before iterating so concurrent calls do not share `lastIndex`.
+ */
+const SECRET_RULES = [
+    {
+        pattern: 'anthropic-api-key',
+        // sk-ant- followed by 40+ url-safe chars. Anthropic keys are
+        // typically 95+ chars; production keys can run 200+ chars. The
+        // greedy `{40,}` plus a negative lookahead terminates cleanly on
+        // any length without an upper bound that would silently miss
+        // longer keys (Claude reviewer P1).
+        regex: /\bsk-ant-[A-Za-z0-9_-]{40,}(?![A-Za-z0-9_-])/g,
+        confidence: 'high',
+    },
+    {
+        pattern: 'openai-project-key',
+        // OpenAI project keys (`sk-proj-…`) include hyphens/underscores
+        // in the tail, so the legacy alphanumeric class would silently
+        // miss them. Anchored to the literal `sk-proj-` prefix and
+        // terminated via lookahead so length never caps detection.
+        regex: /\bsk-proj-[A-Za-z0-9_-]{40,}(?![A-Za-z0-9_-])/g,
+        confidence: 'high',
+    },
+    {
+        pattern: 'openai-sk-key',
+        // OpenAI legacy "sk-" + 32+ alphanumeric. We anchor with a word
+        // boundary so prose like "the SK-Mafia" can't collide. The lower
+        // bound is 20 to align with the spec; OpenAI in practice issues
+        // 48-char keys. Lookahead-terminated so length cannot cap us out.
+        regex: /\bsk-[A-Za-z0-9]{20,}(?![A-Za-z0-9])/g,
+        confidence: 'high',
+    },
+    {
+        pattern: 'github-token',
+        // ghp_ / ghs_ / gho_ / ghu_ + exactly 36 base62 chars (vendor
+        // doc'd shape).
+        regex: /\bgh[psou]_[A-Za-z0-9]{36}\b/g,
+        confidence: 'high',
+    },
+    {
+        pattern: 'aws-access-key-id',
+        // 16 uppercase alphanumerics after `AKIA` — vendor format. Word
+        // boundary keeps `MAKIAYZX...` (unlikely but possible) out.
+        regex: /\bAKIA[0-9A-Z]{16}\b/g,
+        confidence: 'high',
+    },
+    {
+        pattern: 'plane-api-token',
+        // Plane (project management) personal API tokens. Bounded to 20+
+        // url-safe chars after the prefix.
+        regex: /\bplane_api_[A-Za-z0-9]{20,}(?![A-Za-z0-9])/g, // [pugi-leak-ok]
+        confidence: 'high',
+    },
+    {
+        pattern: 'npm-token',
+        // npm_ + 36 base62 chars (vendor format).
+        regex: /\bnpm_[A-Za-z0-9]{36}\b/g,
+        confidence: 'high',
+    },
+    {
+        pattern: 'slack-token',
+        // xoxb / xoxp / xoxo / xoxa / xoxr / xoxs. Slack tokens are
+        // hyphen-segmented; we bound the trailing segment length to dodge
+        // `.*`-style backtracking.
+        regex: /\bxox[bpoars]-[A-Za-z0-9-]{10,}(?![A-Za-z0-9-])/g,
+        confidence: 'high',
+    },
+    {
+        pattern: 'stripe-key',
+        // sk_live_ / sk_test_ + 24+ base62 chars.
+        regex: /\bsk_(?:live|test)_[A-Za-z0-9]{24,}(?![A-Za-z0-9])/g,
+        confidence: 'high',
+    },
+    {
+        pattern: 'private-key-pem',
+        // PEM block headers — RSA / OPENSSH / EC / DSA / PGP. Anchored
+        // alternation, no nested quantifiers.
+        regex: /-----BEGIN (?:RSA|OPENSSH|EC|DSA|PGP) PRIVATE KEY-----/g,
+        confidence: 'high',
+    },
+    {
+        pattern: 'anvil-api-key',
+        // Pugi-internal Anvil keys — both the legacy and scoped shapes.
+        regex: /\b(?:sk_)?anvil_[A-Za-z0-9_-]{16,}(?![A-Za-z0-9_-])/g,
+        confidence: 'high',
+    },
+    {
+        pattern: 'jwt-token',
+        // Three base64url segments separated by `.`. The 20-char lower
+        // bound per segment dodges the "u.s.a" trap; real JWTs have
+        // headers like `eyJhbGciOi…` which are well above this floor.
+        regex: /\beyJ[A-Za-z0-9_-]{18,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\b/g,
+        confidence: 'medium',
+    },
+    {
+        pattern: 'bearer-token',
+        // Authorization-header shape with an opaque 20+ char tail.
+        // Case-insensitive `Bearer` keyword. Bounded tail to avoid
+        // matching whole prose paragraphs.
+        regex: /\b[Bb]earer\s+[A-Za-z0-9_.~+/=-]{20,200}\b/g,
+        confidence: 'medium',
+    },
+];
+/** Resolve the strict-mode setting (env-first, opt-out via "0" / "false"). */
+function resolveStrict(opt) {
+    if (typeof opt === 'boolean')
+        return opt;
+    const raw = process.env.PUGI_MEMORY_SECRET_STRICT;
+    if (raw === undefined)
+        return true;
+    const lowered = raw.trim().toLowerCase();
+    return !(lowered === '0' || lowered === 'false' || lowered === 'no');
+}
+/** Predicate — is the scanner currently disabled via env? */
+export function isScanDisabled() {
+    const raw = process.env.PUGI_MEMORY_SECRET_SCAN_DISABLE;
+    if (raw === undefined)
+        return false;
+    const lowered = raw.trim().toLowerCase();
+    return lowered === '1' || lowered === 'true' || lowered === 'yes';
+}
+/** Compute 1-based line number for a byte offset. */
+function lineNumberFor(text, offset) {
+    let line = 1;
+    for (let i = 0; i < offset && i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10)
+            line += 1;
+    }
+    return line;
+}
+/**
+ * Scan `text` for secret patterns. Returns one `SecretMatch` per hit,
+ * in occurrence order. Empty array means clean.
+ *
+ * The function is pure — it does NOT read env outside of resolving the
+ * strict-mode default for `options.strict`. Callers that need a fully
+ * deterministic invocation should pass `options.strict` explicitly.
+ */
+export function scanForSecrets(text, options) {
+    if (text.length === 0)
+        return [];
+    const strict = resolveStrict(options?.strict);
+    const out = [];
+    for (const rule of SECRET_RULES) {
+        if (!strict && rule.confidence === 'medium')
+            continue;
+        // Clone the regex per-rule so concurrent scans (e.g. parallel
+        // tests) don't share `lastIndex`. This also defends against
+        // accidental mutation if a future rule forgets the `g` flag.
+        const rx = new RegExp(rule.regex.source, rule.regex.flags);
+        for (const m of text.matchAll(rx)) {
+            if (m.index === undefined)
+                continue;
+            out.push({
+                pattern: rule.pattern,
+                match: m[0],
+                offset: m.index,
+                lineNumber: lineNumberFor(text, m.index),
+                confidence: rule.confidence,
+            });
+        }
+    }
+    // Sort by offset so callers see a left-to-right walk of the input
+    // even when multiple rules fired in different orders.
+    out.sort((a, b) => a.offset - b.offset);
+    return out;
+}
+/**
+ * Replace every detected secret with a `[SECRET:<pattern>]` placeholder
+ * and return both the redacted text and the original match list. The
+ * pattern name is included in the placeholder so the operator can see
+ * what category was scrubbed.
+ *
+ * Redaction respects the same strict-mode resolution as `scanForSecrets`.
+ */
+export function redactSecrets(text, options) {
+    const matches = scanForSecrets(text, options);
+    if (matches.length === 0)
+        return { redacted: text, matches };
+    // Walk right-to-left so earlier offsets stay valid as we splice.
+    let redacted = text;
+    for (let i = matches.length - 1; i >= 0; i -= 1) {
+        const m = matches[i];
+        if (m === undefined)
+            continue;
+        const before = redacted.slice(0, m.offset);
+        const after = redacted.slice(m.offset + m.match.length);
+        redacted = `${before}[SECRET:${m.pattern}]${after}`;
+    }
+    return { redacted, matches };
+}
+/**
+ * Hard guard for memory write entry points. Throws a
+ * `MemorySecretGuardError` on any non-empty match set (after the env
+ * disable check). Caller side handles the `--allow-redacted` flow by
+ * calling `redactSecrets` directly.
+ *
+ * Returns the (unchanged) input string when the scan is clean — lets
+ * the call site stay one-liner: `content = assertNoSecrets(content)`.
+ */
+export function assertNoSecrets(text, options) {
+    if (isScanDisabled())
+        return text;
+    const matches = scanForSecrets(text, options);
+    if (matches.length === 0)
+        return text;
+    throw new MemorySecretGuardError(matches);
+}
+/**
+ * Thrown when memory content would persist a credential. The error
+ * carries the structured match list so the CLI can render an
+ * actionable message (pattern names + line numbers) without
+ * re-leaking the secrets back into the operator's terminal.
+ */
+export class MemorySecretGuardError extends Error {
+    matches;
+    constructor(matches) {
+        const names = Array.from(new Set(matches.map((m) => m.pattern))).join(', ');
+        super(`pugi memory: refused to persist content containing secret(s) — pattern(s): ${names}. ` +
+            `Set PUGI_MEMORY_SECRET_SCAN_DISABLE=1 to bypass, or rewrite the content. ` +
+            `Use \`pugi memory write --allow-redacted\` to auto-scrub.`);
+        this.name = 'MemorySecretGuardError';
+        this.matches = matches;
+    }
+}
+/** Stable export for tests + integration call sites. */
+export const SECRET_PATTERN_NAMES = SECRET_RULES.map((r) => r.pattern);
+//# sourceMappingURL=secret-scanner.js.map

package/dist/core/memory-sync/queue.js

@@ -0,0 +1,170 @@
+/**
+ * Pugi memory sync queue .
+ *
+ * Local pending-write queue for `pugi memory` commands when the
+ * operator is offline or the admin-api is unreachable. Each pending
+ * mutation lands on disk as one JSONL line; `pugi memory sync` reads
+ * the queue, fires them to the admin-api in order, and rewrites the
+ * file with only the entries that still failed.
+ *
+ * Storage:
+ *
+ *  ~/.pugi/memory-queue.jsonl         (mode 0600)
+ *
+ * Each line is a fully-typed `PendingMemoryOperation` envelope. The
+ * envelope is forward-compatible: an older CLI reading a JSONL file
+ * written by a newer CLI silently skips lines whose `op` field is
+ * not in its known set (so a partial-rollback scenario doesn't crash
+ * the queue).
+ *
+ * Design intent:
+ *  - Append-only on disk for the hot path (`pugi memory write` /
+ *    `pugi memory forget` queue when offline). Rewrites only on
+ *    successful sync.
+ *  - One file per operator (PUGI_HOME-aware). Queue is local to the
+ *    machine — no cross-host coordination. Multi-device sync is
+ *    deferred to Phase 6 (server-side outbox).
+ *  - No fsync / atomic rename ceremony in v1 — best effort. The
+ *    queue is a convenience surface, not a durability primitive;
+ *    the source of truth is the admin-api row.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { z } from 'zod';
+import { assertNoSecrets } from '../memory/secret-scanner.js';
+/** Six canonical kinds — must mirror `apps/admin-api/src/persona-memory/persona-memory.types.ts`. */
+export const PERSONA_MEMORY_KINDS = [
+    'pattern',
+    'preference',
+    'architecture',
+    'bug',
+    'workflow',
+    'fact',
+];
+const writeOpSchema = z.object({
+    op: z.literal('write'),
+    enqueuedAt: z.string().datetime(),
+    personaSlug: z.string().min(1).max(64),
+    kind: z.enum(PERSONA_MEMORY_KINDS),
+    content: z.string().min(1).max(4000),
+    forgetAfter: z.string().datetime().nullable().optional(),
+});
+const forgetOpSchema = z.object({
+    op: z.literal('forget'),
+    enqueuedAt: z.string().datetime(),
+    id: z.string().min(1),
+});
+const pendingMemoryOpSchema = z.discriminatedUnion('op', [
+    writeOpSchema,
+    forgetOpSchema,
+]);
+/** Default storage path. Override via `PUGI_HOME` for tests / multi-account. */
+export function defaultQueuePath() {
+    const root = process.env.PUGI_HOME ?? resolve(homedir(), '.pugi');
+    return resolve(root, 'memory-queue.jsonl');
+}
+/**
+ * Append one pending operation to the queue file. Creates the parent
+ * directory + file with mode 0600 if missing. Pure-disk, no network.
+ *
+ * Returns the count of pending ops after the append (1-based) so the
+ * CLI command can render "queued (3 pending) — run `pugi memory sync`".
+ */
+export function enqueueMemoryOp(op, pathOverride) {
+    const fullOp = {
+        ...op,
+        enqueuedAt: new Date().toISOString(),
+    };
+    pendingMemoryOpSchema.parse(fullOp);
+    // Backlog (P1 security hardening): refuse to enqueue any write
+    // whose `content` matches a known secret shape (sk-ant-, ghp_, AKIA…
+    // etc). `assertNoSecrets` throws `MemorySecretGuardError` carrying
+    // the matched pattern list, which the CLI catches and renders
+    // without re-leaking the value back to the operator. The opt-out
+    // env (`PUGI_MEMORY_SECRET_SCAN_DISABLE=1`) is honoured inside
+    // `assertNoSecrets` so tests + emergency overrides have a knob.
+    // `forget` ops carry only an id, so they bypass the scan.
+    if (fullOp.op === 'write') {
+        assertNoSecrets(fullOp.content);
+    }
+    const queuePath = pathOverride ?? defaultQueuePath();
+    ensureQueueFile(queuePath);
+    const existing = readFileSync(queuePath, 'utf-8');
+    const line = `${JSON.stringify(fullOp)}\n`;
+    writeFileSync(queuePath, `${existing}${line}`, { encoding: 'utf-8', mode: 0o600 });
+    // Best-effort chmod (in case the file existed already at the wrong mode).
+    try {
+        chmodSync(queuePath, 0o600);
+    }
+    catch {
+        // ignore — the file was just written above, mode might be platform-dependent.
+    }
+    return countPending(queuePath);
+}
+/** Read the queue file and return parsed entries. Skips unknown / malformed lines. */
+export function readMemoryQueue(pathOverride) {
+    const queuePath = pathOverride ?? defaultQueuePath();
+    if (!existsSync(queuePath))
+        return [];
+    const raw = readFileSync(queuePath, 'utf-8');
+    const out = [];
+    for (const line of raw.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = pendingMemoryOpSchema.parse(JSON.parse(trimmed));
+            out.push(parsed);
+        }
+        catch {
+            // forward-compat: a future op kind we don't recognise should not
+            // crash the queue; just drop the line during this read.
+            continue;
+        }
+    }
+    return out;
+}
+/** Rewrite the queue file with `remaining` entries only. Empty array clears the file. */
+export function rewriteMemoryQueue(remaining, pathOverride) {
+    const queuePath = pathOverride ?? defaultQueuePath();
+    ensureQueueFile(queuePath);
+    if (remaining.length === 0) {
+        writeFileSync(queuePath, '', { encoding: 'utf-8', mode: 0o600 });
+        return;
+    }
+    const body = remaining.map((op) => JSON.stringify(op)).join('\n') + '\n';
+    writeFileSync(queuePath, body, { encoding: 'utf-8', mode: 0o600 });
+}
+/** Count pending ops without re-parsing every line individually for the typed shape. */
+export function countPending(pathOverride) {
+    const queuePath = pathOverride ?? defaultQueuePath();
+    if (!existsSync(queuePath))
+        return 0;
+    const raw = readFileSync(queuePath, 'utf-8');
+    let n = 0;
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim().length > 0)
+            n++;
+    }
+    return n;
+}
+/** Quick predicate — was anything ever queued? */
+export function hasPendingOps(pathOverride) {
+    return countPending(pathOverride) > 0;
+}
+function ensureQueueFile(queuePath) {
+    const dir = dirname(queuePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (!existsSync(queuePath)) {
+        writeFileSync(queuePath, '', { encoding: 'utf-8', mode: 0o600 });
+        try {
+            chmodSync(queuePath, 0o600);
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/core/metrics/extract.js

@@ -0,0 +1,113 @@
+/**
+ * Metric extraction primitive (task P1).
+ *
+ * Scans a log buffer line by line for named regex patterns and emits one
+ * `ExtractedMetric` per match. Used by the pugi_eval harness to lift
+ * karpathy-style flat log lines (e.g. `e2e: total=51 pass=45 fail=6
+ * dur=170.48s`) into structured measurements without committing to a
+ * full log-parser dependency.
+ *
+ * Contract:
+ *  - Every supplied pattern MUST contain a numeric capture group 1.
+ *    Patterns lacking a capture group throw a clear error rather than
+ *    silently emitting NaN — a missing group is a programming bug, not
+ *    a data condition.
+ *  - Lines that don't match are skipped, not reported. Callers that
+ *    need per-line trace coverage should layer their own scanner.
+ *  - Each match emits a fresh ISO-8601 timestamp via `new Date()`. The
+ *    timestamp reflects extraction time, not the moment the log line
+ *    was produced — log producers that need true event time should
+ *    embed it themselves and pattern it out.
+ *  - Regex `lastIndex` state is not relied upon: we test each line as
+ *    a self-contained string. Patterns may be sticky or global without
+ *    affecting correctness.
+ */
+/**
+ * Scan `logText` for each named pattern and emit one metric per match.
+ *
+ * Output order: outer loop over the patterns map insertion order, inner
+ * loop over lines in source order. So all `pugi_score` hits arrive
+ * before all `tokens_in` hits when both patterns fire on the same
+ * buffer. Tests rely on this stable ordering; do not switch to a
+ * line-major loop without updating the spec.
+ */
+export function extractMetrics(logText, patterns) {
+    const lines = logText.split(/\r?\n/);
+    const out = [];
+    for (const [name, pattern] of Object.entries(patterns)) {
+        assertHasCaptureGroup(name, pattern);
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i] ?? '';
+            const match = line.match(pattern);
+            if (!match)
+                continue;
+            const raw = match[1];
+            if (raw === undefined)
+                continue;
+            const value = parseFloat(raw);
+            if (!Number.isFinite(value))
+                continue;
+            out.push({
+                name,
+                value,
+                ts: new Date().toISOString(),
+                line: i + 1,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Common pugi_eval log patterns. Case-insensitive on the metric key so
+ * `Pugi_Score`, `PUGI_SCORE`, and `pugi_score` all match — karpathy-style
+ * harness output varies. The numeric capture group is always group 1.
+ *
+ * Separator class `[:\s=]+` accepts `key: value`, `key=value`, and
+ * `key value` shapes. Numeric class `[0-9.]+` is liberal enough for
+ * scientific-notation-free floats; exotic encodings (1e6, NaN, hex)
+ * are not in scope — pugi_eval emits decimal-only.
+ */
+export const DEFAULT_PATTERNS = {
+    pugi_score: /pugi_score[:\s=]+([0-9.]+)/i,
+    tokens_in: /tokens.in[:\s=]+([0-9]+)/i,
+    tokens_out: /tokens.out[:\s=]+([0-9]+)/i,
+    wall_clock_sec: /wall.clock.*?([0-9.]+)\s*s(?:ec)?/i,
+    dur: /dur[:\s=]+([0-9.]+)/i,
+    pass: /pass[:\s=]+([0-9]+)/i,
+    fail: /fail[:\s=]+([0-9]+)/i,
+};
+/**
+ * Validate that `pattern` has at least one capture group by probing the
+ * regex source. Throws a clear `Error` rather than letting `match[1]`
+ * silently return `undefined` at every line — a missing group is a
+ * programmer error and we want it loud on first call.
+ *
+ * Detection is heuristic but conservative: counts `(` characters that
+ * are not preceded by `\` and not opening a `(?:` non-capturing group
+ * or `(?=` / `(?!` lookaround. Good enough for the patterns we ship;
+ * patterns that fool the heuristic will still be caught by the runtime
+ * `parseFloat(undefined) → NaN` skip — they just won't emit metrics.
+ */
+function assertHasCaptureGroup(name, pattern) {
+    const src = pattern.source;
+    let depth = 0;
+    for (let i = 0; i < src.length; i += 1) {
+        const ch = src[i];
+        if (ch === '\\') {
+            i += 1;
+            continue;
+        }
+        if (ch !== '(')
+            continue;
+        const next = src[i + 1];
+        const next2 = src[i + 2];
+        if (next === '?' && (next2 === ':' || next2 === '=' || next2 === '!' || next2 === '<')) {
+            continue;
+        }
+        depth += 1;
+    }
+    if (depth === 0) {
+        throw new Error(`extractMetrics: pattern "${name}" has no capture group; add (...) around the numeric value`);
+    }
+}
+//# sourceMappingURL=extract.js.map

package/dist/core/modes/roo-modes.js

@@ -0,0 +1,68 @@
+/**
+ * @file Defines the operational modes for the Roo agent, controlling tool access and behavior.
+ */
+export const MODES = {
+    architect: {
+        name: 'architect',
+        description: 'Researches and proposes solutions, but does not implement them.',
+        allowed_groups: ['read', 'web', 'memory'],
+        system_prompt_addendum: 'You are an architect. Read + propose. Do not edit.',
+    },
+    code: {
+        name: 'code',
+        description: 'Implements code changes as specified.',
+        allowed_groups: ['read', 'edit', 'bash', 'web', 'mcp', 'memory'],
+        system_prompt_addendum: 'Implement как specified.',
+    },
+    ask: {
+        name: 'ask',
+        description: 'Answers questions about the codebase without making changes.',
+        allowed_groups: ['read', 'web', 'memory'],
+        system_prompt_addendum: 'Answer questions. Do not modify state.',
+    },
+    debug: {
+        name: 'debug',
+        description: 'Investigates issues and can run commands, but requires approval for edits.',
+        allowed_groups: ['read', 'bash', 'web', 'memory'],
+        system_prompt_addendum: 'Investigate root cause. Edit only after explicit user approval.',
+    },
+    orchestrator: {
+        name: 'orchestrator',
+        description: 'Coordinates sub-agents to accomplish complex tasks.',
+        allowed_groups: ['read', 'web', 'agent_spawn', 'memory'],
+        system_prompt_addendum: 'Coordinate sub-agents. Delegate edits.',
+    },
+};
+/**
+ * Checks if a specific tool is allowed in a given agent mode.
+ *
+ * @param mode The current mode of the agent.
+ * @param tool The name of the tool being checked.
+ * @param group The tool group the tool belongs to.
+ * @returns True if the tool is allowed, false otherwise.
+ */
+export function isToolAllowed(mode, tool, group) {
+    const modeDef = MODES[mode];
+    if (!modeDef) {
+        return false;
+    }
+    const groupAllowed = modeDef.allowed_groups.includes(group);
+    if (!groupAllowed) {
+        return false;
+    }
+    const toolDenied = modeDef.denied_tools?.includes(tool) ?? false;
+    if (toolDenied) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Retrieves the system prompt addendum for a given mode.
+ *
+ * @param mode The current mode of the agent.
+ * @returns The system prompt addendum string, or an empty string if none is defined.
+ */
+export function getModeAddendum(mode) {
+    return MODES[mode]?.system_prompt_addendum ?? '';
+}
+//# sourceMappingURL=roo-modes.js.map