siclaw 0.1.0 → 0.1.2

package/dist/shared/metrics.js

@@ -0,0 +1,185 @@
+/**
+ * Prometheus metrics subscriber — the ONLY file that depends on prom-client.
+ *
+ * Subscribes to the diagnostic event bus and maps events to Prometheus metrics.
+ * Business code never imports this module directly — it only calls emitDiagnostic().
+ *
+ * Importing this module (side-effect import) registers the subscriber automatically.
+ */
+import { Counter, Gauge, Histogram, Registry } from "prom-client";
+import { onDiagnostic } from "./diagnostic-events.js";
+/**
+ * Check bearer token authentication for /metrics endpoints.
+ * Returns true if the request is authorized (or no token is configured).
+ * Returns false and sends 401 response if unauthorized.
+ */
+export function checkMetricsAuth(req, res, configuredToken) {
+    const token = configuredToken || process.env.SICLAW_METRICS_TOKEN;
+    if (token && req.headers.authorization !== `Bearer ${token}`) {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Unauthorized" }));
+        return false;
+    }
+    return true;
+}
+export const metricsRegistry = new Registry();
+/** Whether to include user_id label on token/cost metrics (dynamic, refreshable) */
+let includeUserId = process.env.SICLAW_METRICS_USER_ID !== "false";
+/** Update the includeUserId flag at runtime (called by Gateway when DB config changes) */
+export function setIncludeUserId(value) {
+    includeUserId = value;
+}
+// ── Phase 1: Core metrics (7) ──
+const tokensTotal = new Counter({
+    name: "siclaw_tokens_total",
+    help: "Cumulative token consumption",
+    labelNames: ["type", "provider", "model", "user_id"],
+    registers: [metricsRegistry],
+});
+const costUsdTotal = new Counter({
+    name: "siclaw_cost_usd_total",
+    help: "Cumulative LLM cost in USD",
+    labelNames: ["provider", "model", "user_id"],
+    registers: [metricsRegistry],
+});
+const promptDurationMs = new Histogram({
+    name: "siclaw_prompt_duration_ms",
+    help: "Prompt end-to-end processing latency in milliseconds",
+    labelNames: ["provider", "model", "outcome"],
+    buckets: [500, 1_000, 2_500, 5_000, 10_000, 30_000, 60_000, 120_000, 300_000],
+    registers: [metricsRegistry],
+});
+const promptsTotal = new Counter({
+    name: "siclaw_prompts_total",
+    help: "Total prompts processed",
+    labelNames: ["provider", "model", "outcome"],
+    registers: [metricsRegistry],
+});
+const sessionsActive = new Gauge({
+    name: "siclaw_sessions_active",
+    help: "Current number of active sessions",
+    registers: [metricsRegistry],
+});
+const toolCallsTotal = new Counter({
+    name: "siclaw_tool_calls_total",
+    help: "Total tool invocations",
+    labelNames: ["tool_name", "outcome"],
+    registers: [metricsRegistry],
+});
+const wsConnections = new Gauge({
+    name: "siclaw_ws_connections",
+    help: "Current number of WebSocket connections",
+    registers: [metricsRegistry],
+});
+// ── Skill metrics ──
+// NOTE: siclaw_skill_calls_total uses skill_name label which is unbounded.
+// If personal skill count grows large, consider dropping this counter and
+// relying solely on the low-cardinality siclaw_skill_calls_by_scope_total.
+const skillCallsTotal = new Counter({
+    name: "siclaw_skill_calls_total",
+    help: "Total skill invocations",
+    labelNames: ["skill_name", "scope", "outcome"],
+    registers: [metricsRegistry],
+});
+const skillCallsByScopeTotal = new Counter({
+    name: "siclaw_skill_calls_by_scope_total",
+    help: "Total skill invocations aggregated by scope (low-cardinality fallback)",
+    labelNames: ["scope", "outcome"],
+    registers: [metricsRegistry],
+});
+// ── Phase 2: Session health metrics (4) ──
+const contextTokensUsed = new Gauge({
+    name: "siclaw_context_tokens_used",
+    help: "Current context window tokens used (sampled per turn)",
+    labelNames: ["provider", "model"],
+    registers: [metricsRegistry],
+});
+const contextTokensLimit = new Gauge({
+    name: "siclaw_context_tokens_limit",
+    help: "Context window token limit (sampled per turn)",
+    labelNames: ["provider", "model"],
+    registers: [metricsRegistry],
+});
+const sessionStuckTotal = new Counter({
+    name: "siclaw_session_stuck_total",
+    help: "Number of stuck sessions detected",
+    registers: [metricsRegistry],
+});
+const sessionStuckAgeMs = new Histogram({
+    name: "siclaw_session_stuck_age_ms",
+    help: "Duration of stuck sessions in milliseconds",
+    buckets: [30_000, 60_000, 120_000, 300_000],
+    registers: [metricsRegistry],
+});
+// ── Event → metric mapping ──
+function handleDiagnostic(event) {
+    switch (event.type) {
+        case "prompt_complete": {
+            const { prev, curr, model, durationMs, outcome, userId } = event;
+            const provider = model?.provider ?? "unknown";
+            const modelId = model?.id ?? "unknown";
+            // Token deltas (session stats are cumulative — subtract pre-prompt snapshot)
+            const dInput = curr.tokens.input - prev.tokens.input;
+            const dOutput = curr.tokens.output - prev.tokens.output;
+            const dCacheRead = curr.tokens.cacheRead - prev.tokens.cacheRead;
+            const dCacheWrite = curr.tokens.cacheWrite - prev.tokens.cacheWrite;
+            const baseLabels = includeUserId && userId
+                ? { provider, model: modelId, user_id: userId }
+                : { provider, model: modelId };
+            if (dInput > 0)
+                tokensTotal.inc({ ...baseLabels, type: "input" }, dInput);
+            if (dOutput > 0)
+                tokensTotal.inc({ ...baseLabels, type: "output" }, dOutput);
+            if (dCacheRead > 0)
+                tokensTotal.inc({ ...baseLabels, type: "cache_read" }, dCacheRead);
+            if (dCacheWrite > 0)
+                tokensTotal.inc({ ...baseLabels, type: "cache_write" }, dCacheWrite);
+            // Cost delta
+            const dCost = curr.cost - prev.cost;
+            if (dCost > 0)
+                costUsdTotal.inc(baseLabels, dCost);
+            // Prompt duration + count
+            const outcomeLabels = { provider, model: modelId, outcome };
+            promptDurationMs.observe(outcomeLabels, durationMs);
+            promptsTotal.inc(outcomeLabels);
+            break;
+        }
+        case "session_created":
+            sessionsActive.inc();
+            break;
+        case "session_released":
+            sessionsActive.dec();
+            break;
+        case "tool_call":
+            toolCallsTotal.inc({ tool_name: event.toolName, outcome: event.outcome });
+            break;
+        case "skill_call":
+            skillCallsTotal.inc({
+                skill_name: event.skillName,
+                scope: event.scope,
+                outcome: event.outcome,
+            });
+            skillCallsByScopeTotal.inc({
+                scope: event.scope,
+                outcome: event.outcome,
+            });
+            break;
+        case "ws_connected":
+            wsConnections.inc();
+            break;
+        case "ws_disconnected":
+            wsConnections.dec();
+            break;
+        case "context_usage":
+            contextTokensUsed.set({ provider: event.provider, model: event.model }, event.tokensUsed);
+            contextTokensLimit.set({ provider: event.provider, model: event.model }, event.tokensLimit);
+            break;
+        case "session_stuck":
+            sessionStuckTotal.inc();
+            sessionStuckAgeMs.observe(event.idleMs);
+            break;
+    }
+}
+// Auto-register subscriber when this module is imported
+onDiagnostic(handleDiagnostic);
+//# sourceMappingURL=metrics.js.map

package/dist/shared/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/shared/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,YAAY,EAAwB,MAAM,wBAAwB,CAAC;AAE5E;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAyB,EAAE,GAAwB,EAAE,eAAwB;IAC5G,MAAM,KAAK,GAAG,eAAe,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IAClE,IAAI,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,UAAU,KAAK,EAAE,EAAE,CAAC;QAC7D,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAC3D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;QACnD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,QAAQ,EAAE,CAAC;AAE9C,oFAAoF;AACpF,IAAI,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,KAAK,OAAO,CAAC;AAEnE,0FAA0F;AAC1F,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,aAAa,GAAG,KAAK,CAAC;AACxB,CAAC;AAED,kCAAkC;AAElC,MAAM,WAAW,GAAG,IAAI,OAAO,CAAC;IAC9B,IAAI,EAAE,qBAAqB;IAC3B,IAAI,EAAE,8BAA8B;IACpC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,CAAU;IAC7D,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,IAAI,OAAO,CAAC;IAC/B,IAAI,EAAE,uBAAuB;IAC7B,IAAI,EAAE,4BAA4B;IAClC,UAAU,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,CAAU;IACrD,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,gBAAgB,GAAG,IAAI,SAAS,CAAC;IACrC,IAAI,EAAE,2BAA2B;IACjC,IAAI,EAAE,sDAAsD;IAC5D,UAAU,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,CAAU;IACrD,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC;IAC7E,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,IAAI,OAAO,CAAC;IAC/B,IAAI,EAAE,sBAAsB;IAC5B,IAAI,EAAE,yBAAyB;IAC/B,UAAU,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,CAAU;IACrD,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,cAAc,GAAG,IAAI,KAAK,CAAC;IAC/B,IAAI,EAAE,wBAAwB;IAC9B,IAAI,EAAE,mCAAmC;IACzC,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,cAAc,GAAG,IAAI,OAAO,CAAC;IACjC,IAAI,EAAE,yBAAyB;IAC/B,IAAI,EAAE,wBAAwB;IAC9B,UAAU,EAAE,CAAC,WAAW,EAAE,SAAS,CAAU;IAC7C,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,aAAa,GAAG,IAAI,KAAK,CAAC;IAC9B,IAAI,EAAE,uBAAuB;IAC7B,IAAI,EAAE,yCAAyC;IAC/C,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,sBAAsB;AACtB,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAE3E,MAAM,eAAe,GAAG,IAAI,OAAO,CAAC;IAClC,IAAI,EAAE,0BAA0B;IAChC,IAAI,EAAE,yBAAyB;IAC/B,UAAU,EAAE,CAAC,YAAY,EAAE,OAAO,EAAE,SAAS,CAAU;IACvD,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,sBAAsB,GAAG,IAAI,OAAO,CAAC;IACzC,IAAI,EAAE,mCAAmC;IACzC,IAAI,EAAE,wEAAwE;IAC9E,UAAU,EAAE,CAAC,OAAO,EAAE,SAAS,CAAU;IACzC,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,4CAA4C;AAE5C,MAAM,iBAAiB,GAAG,IAAI,KAAK,CAAC;IAClC,IAAI,EAAE,4BAA4B;IAClC,IAAI,EAAE,uDAAuD;IAC7D,UAAU,EAAE,CAAC,UAAU,EAAE,OAAO,CAAU;IAC1C,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,kBAAkB,GAAG,IAAI,KAAK,CAAC;IACnC,IAAI,EAAE,6BAA6B;IACnC,IAAI,EAAE,+CAA+C;IACrD,UAAU,EAAE,CAAC,UAAU,EAAE,OAAO,CAAU;IAC1C,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAG,IAAI,OAAO,CAAC;IACpC,IAAI,EAAE,4BAA4B;IAClC,IAAI,EAAE,mCAAmC;IACzC,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAG,IAAI,SAAS,CAAC;IACtC,IAAI,EAAE,6BAA6B;IACnC,IAAI,EAAE,4CAA4C;IAClD,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC;IAC3C,SAAS,EAAE,CAAC,eAAe,CAAC;CAC7B,CAAC,CAAC;AAEH,+BAA+B;AAE/B,SAAS,gBAAgB,CAAC,KAAsB;IAC9C,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,iBAAiB,CAAC,CAAC,CAAC;YACvB,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;YACjE,MAAM,QAAQ,GAAG,KAAK,EAAE,QAAQ,IAAI,SAAS,CAAC;YAC9C,MAAM,OAAO,GAAG,KAAK,EAAE,EAAE,IAAI,SAAS,CAAC;YAEvC,6EAA6E;YAC7E,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;YACrD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;YACxD,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;YACjE,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;YAEpE,MAAM,UAAU,GAAG,aAAa,IAAI,MAAM;gBACxC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE;gBAC/C,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YAEjC,IAAI,MAAM,GAAG,CAAC;gBAAE,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;YAC1E,IAAI,OAAO,GAAG,CAAC;gBAAE,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,OAAO,CAAC,CAAC;YAC7E,IAAI,UAAU,GAAG,CAAC;gBAAE,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,UAAU,CAAC,CAAC;YACvF,IAAI,WAAW,GAAG,CAAC;gBAAE,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,UAAU,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,WAAW,CAAC,CAAC;YAE1F,aAAa;YACb,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;YACpC,IAAI,KAAK,GAAG,CAAC;gBAAE,YAAY,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;YAEnD,0BAA0B;YAC1B,MAAM,aAAa,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;YAC5D,gBAAgB,CAAC,OAAO,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;YACpD,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YAChC,MAAM;QACR,CAAC;QAED,KAAK,iBAAiB;YACpB,cAAc,CAAC,GAAG,EAAE,CAAC;YACrB,MAAM;QAER,KAAK,kBAAkB;YACrB,cAAc,CAAC,GAAG,EAAE,CAAC;YACrB,MAAM;QAER,KAAK,WAAW;YACd,cAAc,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAC1E,MAAM;QAER,KAAK,YAAY;YACf,eAAe,CAAC,GAAG,CAAC;gBAClB,UAAU,EAAE,KAAK,CAAC,SAAS;gBAC3B,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC;YACH,sBAAsB,CAAC,GAAG,CAAC;gBACzB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC;YACH,MAAM;QAER,KAAK,cAAc;YACjB,aAAa,CAAC,GAAG,EAAE,CAAC;YACpB,MAAM;QAER,KAAK,iBAAiB;YACpB,aAAa,CAAC,GAAG,EAAE,CAAC;YACpB,MAAM;QAER,KAAK,eAAe;YAClB,iBAAiB,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;YAC1F,kBAAkB,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;YAC5F,MAAM;QAER,KAAK,eAAe;YAClB,iBAAiB,CAAC,GAAG,EAAE,CAAC;YACxB,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACxC,MAAM;IACV,CAAC;AACH,CAAC;AAED,wDAAwD;AACxD,YAAY,CAAC,gBAAgB,CAAC,CAAC"}

package/dist/shared/path-utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared path traversal validation utility.
+ *
+ * Used by resource handlers, credential manager, and http-server to ensure
+ * resolved paths stay within a designated base directory.
+ */
+/**
+ * Resolve a path under a base directory, throwing if it escapes.
+ *
+ * @param base - The trusted base directory (must be an absolute, resolved path)
+ * @param segments - Untrusted path segments to join under base
+ * @returns The resolved absolute path guaranteed to be under base
+ * @throws Error if the resolved path escapes the base directory
+ */
+export declare function resolveUnderDir(base: string, ...segments: string[]): string;

package/dist/shared/path-utils.js

@@ -0,0 +1,23 @@
+/**
+ * Shared path traversal validation utility.
+ *
+ * Used by resource handlers, credential manager, and http-server to ensure
+ * resolved paths stay within a designated base directory.
+ */
+import path from "node:path";
+/**
+ * Resolve a path under a base directory, throwing if it escapes.
+ *
+ * @param base - The trusted base directory (must be an absolute, resolved path)
+ * @param segments - Untrusted path segments to join under base
+ * @returns The resolved absolute path guaranteed to be under base
+ * @throws Error if the resolved path escapes the base directory
+ */
+export function resolveUnderDir(base, ...segments) {
+    const resolved = path.resolve(base, ...segments);
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+        throw new Error(`Path escapes base directory: ${resolved}`);
+    }
+    return resolved;
+}
+//# sourceMappingURL=path-utils.js.map

package/dist/shared/path-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../src/shared/path-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,GAAG,QAAkB;IACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;IACjD,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/shared/retry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Retry with exponential backoff — generic utility for HTTP calls.
+ *
+ * Pattern borrowed from src/memory/embeddings.ts.
+ */
+export interface RetryOptions {
+    /** Maximum number of attempts (including the first). Default: 3 */
+    maxAttempts?: number;
+    /** Base delay in ms before first retry. Default: 1000 */
+    baseDelayMs?: number;
+    /** Maximum delay cap in ms. Default: 10000 */
+    maxDelayMs?: number;
+    /** Optional predicate — return false to skip retries for certain errors */
+    shouldRetry?: (err: unknown) => boolean;
+    /** Label for log messages */
+    label?: string;
+}
+/**
+ * Execute `fn` with retry + exponential backoff.
+ *
+ * Delay formula: min(maxDelayMs, baseDelayMs * 2^attempt * (1 + random()*0.2))
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+/**
+ * Typed HTTP error with status code — avoids fragile regex on message strings.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Default shouldRetry predicate for HTTP calls:
+ * retry on network errors and 5xx / 429, skip on other 4xx.
+ */
+export declare function shouldRetryHttp(err: unknown): boolean;

package/dist/shared/retry.js

@@ -0,0 +1,61 @@
+/**
+ * Retry with exponential backoff — generic utility for HTTP calls.
+ *
+ * Pattern borrowed from src/memory/embeddings.ts.
+ */
+/**
+ * Execute `fn` with retry + exponential backoff.
+ *
+ * Delay formula: min(maxDelayMs, baseDelayMs * 2^attempt * (1 + random()*0.2))
+ */
+export async function withRetry(fn, opts = {}) {
+    const { maxAttempts = 3, baseDelayMs = 1000, maxDelayMs = 10_000, shouldRetry, label, } = opts;
+    let lastError;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            // Check if we should retry this error
+            if (shouldRetry && !shouldRetry(err)) {
+                throw err;
+            }
+            if (attempt + 1 >= maxAttempts) {
+                break; // No more attempts
+            }
+            const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt * (1 + Math.random() * 0.2));
+            const tag = label ? `[retry:${label}]` : "[retry]";
+            console.warn(`${tag} Attempt ${attempt + 1}/${maxAttempts} failed, retrying in ${Math.round(delay)}ms:`, err instanceof Error ? err.message : err);
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}
+/**
+ * Typed HTTP error with status code — avoids fragile regex on message strings.
+ */
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "HttpError";
+    }
+}
+/**
+ * Default shouldRetry predicate for HTTP calls:
+ * retry on network errors and 5xx / 429, skip on other 4xx.
+ */
+export function shouldRetryHttp(err) {
+    if (err instanceof HttpError) {
+        if (err.status === 429)
+            return true; // Rate limited — retry
+        if (err.status >= 400 && err.status < 500)
+            return false; // Client error — don't retry
+        return true; // 5xx — retry
+    }
+    // Network error or non-HTTP — retry
+    return true;
+}
+//# sourceMappingURL=retry.js.map

package/dist/shared/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/shared/retry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,OAAqB,EAAE;IAEvB,MAAM,EACJ,WAAW,GAAG,CAAC,EACf,WAAW,GAAG,IAAI,EAClB,UAAU,GAAG,MAAM,EACnB,WAAW,EACX,KAAK,GACN,GAAG,IAAI,CAAC;IAET,IAAI,SAAkB,CAAC;IAEvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAG,CAAC;YAEhB,sCAAsC;YACtC,IAAI,WAAW,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;gBACrC,MAAM,GAAG,CAAC;YACZ,CAAC;YAED,IAAI,OAAO,GAAG,CAAC,IAAI,WAAW,EAAE,CAAC;gBAC/B,MAAM,CAAC,mBAAmB;YAC5B,CAAC;YAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,UAAU,EACV,WAAW,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CACvD,CAAC;YACF,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,UAAU,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;YACnD,OAAO,CAAC,IAAI,CACV,GAAG,GAAG,YAAY,OAAO,GAAG,CAAC,IAAI,WAAW,wBAAwB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAC1F,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CACzC,CAAC;YAEF,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,MAAM,SAAS,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEhB;IADlB,YACkB,MAAc,EAC9B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,WAAM,GAAN,MAAM,CAAQ;QAI9B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,GAAG,YAAY,SAAS,EAAE,CAAC;QAC7B,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC,CAAC,uBAAuB;QAC5D,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG;YAAE,OAAO,KAAK,CAAC,CAAC,6BAA6B;QACtF,OAAO,IAAI,CAAC,CAAC,cAAc;IAC7B,CAAC;IACD,oCAAoC;IACpC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/tools/command-sets.d.ts

@@ -29,6 +29,9 @@ export declare function getCommandBinary(cmd: string): string;
  * whitelisted. Use grep + cut/tr/head/tail/jq for text processing instead.
  */
 export declare const ALLOWED_COMMANDS: Set<string>;
+/** Map each command to its functional category. */
+export declare const COMMAND_CATEGORIES: Record<string, string>;
+export declare const CONTEXT_CATEGORIES: Record<string, readonly string[]>;
 /**
  * Declarative command validation rule.
  * JSON-serializable: no Set, no function, no RegExp.
@@ -38,6 +41,14 @@ export interface CommandRule {
     command: string;
     category?: string;
     description?: string;
+    /** Execution contexts where this rule applies. Absent → all contexts. */
+    contexts?: string[];
+    /** If true, command must appear after a pipe | operator (stdin-only). */
+    pipeOnly?: boolean;
+    /** If true, block positional args that look like file paths (/, ./, ../, ~). */
+    noFilePaths?: boolean;
+    /** Flags that are explicitly blocked (checked per-character for short flags). */
+    blockedFlags?: string[];
     /** Flag whitelist. Present → check flags; absent → all flags allowed. */
     allowedFlags?: string[];
     /** Subcommand/action whitelist at a given positional position. */
@@ -52,10 +63,15 @@ export interface CommandRule {
     /** Delegate to a named custom validator function. */
     customValidator?: string;
 }
-export declare const COMMAND_RULES: Record<string, CommandRule>;
+export declare const COMMAND_RULES: Record<string, CommandRule | CommandRule[]>;
 /**
  * Apply extra security restrictions to whitelisted commands.
  * Takes a raw command string, parses it internally.
+ * Optionally accepts context (for context-specific rules) and piped
+ * (for pipe-only enforcement).
  * Returns an error message string if blocked, or null if allowed.
  */
-export declare function validateCommandRestrictions(cmd: string): string | null;
+export declare function validateCommandRestrictions(cmd: string, options?: {
+    context?: string;
+    piped?: boolean;
+}): string | null;