@kernel.chat/kbot 4.0.1 → 4.1.0

package/dist/futures/persona/check.d.ts

@@ -0,0 +1,45 @@
+import { PermissionGrant, Persona, Verdict } from './types.js';
+/**
+ * Reset all rate-limit state. Test-only seam; not exported from index.ts.
+ */
+export declare function _resetRateLimits(): void;
+/**
+ * Resolve (persona, tool, args) → Verdict.
+ *
+ * Iterates scopes in order; the first scope whose toolPattern matches and
+ * whose argConstraints + rateLimit + blast-radius all pass produces an
+ * `allowed: true` verdict. If a scope's toolPattern matches but a check
+ * fails, we continue checking later scopes — a denial on one scope doesn't
+ * forbid a later, more permissive scope.
+ *
+ * If no scope matches the tool name at all, the verdict is denied with
+ * reason "no scope matched". If scopes matched but all failed sub-checks,
+ * the verdict is denied with the *last* failure reason.
+ */
+export declare function canInvoke(persona: Persona, toolName: string, args: Record<string, unknown>, opts?: {
+    now?: number;
+}): Verdict;
+/**
+ * Throws PermissionDeniedError if canInvoke yields a denied verdict.
+ * Returns the verdict on success for callers that want to inspect matchedScope.
+ */
+export declare function enforce(grant: PermissionGrant, opts?: {
+    now?: number;
+}): Verdict;
+/**
+ * Compose multiple personas into a single one.
+ * - id: joined with "+"
+ * - description: joined with "; "
+ * - scopes: concatenated (canInvoke iterates in order, so earliest wins ties)
+ * - maxBlastRadius: max over all inputs (undefined treated as 'none')
+ *
+ * Rate-limit state is keyed on the *resulting* persona's id, so merged
+ * personas have their own counter independent of the inputs.
+ */
+export declare function mergePersonas(...personas: Persona[]): Persona;
+/**
+ * Lookup helper. Throws on miss so callers fail loudly rather than silently
+ * proceeding without a scope.
+ */
+export declare function loadPersona(id: string, registry: Record<string, Persona>): Persona;
+//# sourceMappingURL=check.d.ts.map

package/dist/futures/persona/check.js

@@ -0,0 +1,205 @@
+// futures/persona/check — runtime resolver for (persona, tool, args) → Verdict.
+//
+// Pure resolution + a module-level Map for rate-limit counters. The Map is
+// process-scoped, which is correct for a single CLI run; longer-lived state
+// (e.g. across daemon restarts) is out of scope for v5 phase 1.
+import { BLAST_RADIUS_ORDER, PermissionDeniedError, } from './types.js';
+/** keyed by `${persona.id}::${toolName}` */
+const RATE_LIMIT_STATE = new Map();
+/**
+ * Reset all rate-limit state. Test-only seam; not exported from index.ts.
+ */
+export function _resetRateLimits() {
+    RATE_LIMIT_STATE.clear();
+}
+function rateKey(personaId, toolName) {
+    return `${personaId}::${toolName}`;
+}
+function blastRadiusRank(r) {
+    return BLAST_RADIUS_ORDER.indexOf(r);
+}
+function maxBlastRadius(a, b) {
+    return blastRadiusRank(a) >= blastRadiusRank(b) ? a : b;
+}
+function patternMatches(pattern, toolName) {
+    if (typeof pattern === 'string')
+        return pattern === toolName;
+    return pattern.test(toolName);
+}
+function checkArgRule(argName, value, rule) {
+    // type
+    if (rule.type === 'enum') {
+        if (!rule.allowedValues || !rule.allowedValues.includes(value)) {
+            return { ok: false, reason: `arg "${argName}" not in allowedValues` };
+        }
+        return { ok: true };
+    }
+    if (rule.type === 'string') {
+        if (typeof value !== 'string')
+            return { ok: false, reason: `arg "${argName}" must be string` };
+        if (rule.pattern) {
+            const matched = rule.pattern.test(value);
+            if (rule.denyPattern && matched) {
+                return { ok: false, reason: `arg "${argName}" matches deny pattern` };
+            }
+            if (!rule.denyPattern && !matched) {
+                return { ok: false, reason: `arg "${argName}" does not match required pattern` };
+            }
+        }
+        if (rule.min !== undefined && value.length < rule.min) {
+            return { ok: false, reason: `arg "${argName}" shorter than min=${rule.min}` };
+        }
+        if (rule.max !== undefined && value.length > rule.max) {
+            return { ok: false, reason: `arg "${argName}" longer than max=${rule.max}` };
+        }
+        return { ok: true };
+    }
+    if (rule.type === 'number') {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            return { ok: false, reason: `arg "${argName}" must be number` };
+        }
+        if (rule.min !== undefined && value < rule.min) {
+            return { ok: false, reason: `arg "${argName}" below min=${rule.min}` };
+        }
+        if (rule.max !== undefined && value > rule.max) {
+            return { ok: false, reason: `arg "${argName}" above max=${rule.max}` };
+        }
+        if (rule.allowedValues && !rule.allowedValues.includes(value)) {
+            return { ok: false, reason: `arg "${argName}" not in allowedValues` };
+        }
+        return { ok: true };
+    }
+    if (rule.type === 'boolean') {
+        if (typeof value !== 'boolean')
+            return { ok: false, reason: `arg "${argName}" must be boolean` };
+        if (rule.allowedValues && !rule.allowedValues.includes(value)) {
+            return { ok: false, reason: `arg "${argName}" not in allowedValues` };
+        }
+        return { ok: true };
+    }
+    return { ok: false, reason: `arg "${argName}" unknown rule type` };
+}
+function checkArgs(scope, args) {
+    if (!scope.argConstraints)
+        return { ok: true };
+    for (const [argName, rule] of Object.entries(scope.argConstraints)) {
+        const result = checkArgRule(argName, args[argName], rule);
+        if (!result.ok)
+            return result;
+    }
+    return { ok: true };
+}
+function checkRateLimit(personaId, toolName, scope, now) {
+    if (!scope.rateLimit)
+        return { ok: true };
+    const { max, windowMs } = scope.rateLimit;
+    const key = rateKey(personaId, toolName);
+    const bucket = RATE_LIMIT_STATE.get(key) ?? { hits: [] };
+    // drop hits outside the window
+    bucket.hits = bucket.hits.filter((ts) => now - ts < windowMs);
+    if (bucket.hits.length >= max) {
+        RATE_LIMIT_STATE.set(key, bucket);
+        return { ok: false, reason: `rate limit exceeded (${max}/${windowMs}ms)` };
+    }
+    bucket.hits.push(now);
+    RATE_LIMIT_STATE.set(key, bucket);
+    return { ok: true };
+}
+/**
+ * Resolve (persona, tool, args) → Verdict.
+ *
+ * Iterates scopes in order; the first scope whose toolPattern matches and
+ * whose argConstraints + rateLimit + blast-radius all pass produces an
+ * `allowed: true` verdict. If a scope's toolPattern matches but a check
+ * fails, we continue checking later scopes — a denial on one scope doesn't
+ * forbid a later, more permissive scope.
+ *
+ * If no scope matches the tool name at all, the verdict is denied with
+ * reason "no scope matched". If scopes matched but all failed sub-checks,
+ * the verdict is denied with the *last* failure reason.
+ */
+export function canInvoke(persona, toolName, args, opts) {
+    const now = opts?.now ?? Date.now();
+    let lastFailure = null;
+    let anyToolMatch = false;
+    const personaCap = persona.maxBlastRadius;
+    for (const scope of persona.scopes) {
+        if (!patternMatches(scope.toolPattern, toolName))
+            continue;
+        anyToolMatch = true;
+        // enforce blast-radius cap
+        const scopeRadius = scope.blastRadius ?? personaCap ?? 'none';
+        if (personaCap && blastRadiusRank(scopeRadius) > blastRadiusRank(personaCap)) {
+            lastFailure = {
+                reason: `scope blastRadius=${scopeRadius} exceeds persona max=${personaCap}`,
+                scope,
+            };
+            continue;
+        }
+        const argResult = checkArgs(scope, args);
+        if (!argResult.ok) {
+            lastFailure = { reason: argResult.reason, scope };
+            continue;
+        }
+        const rateResult = checkRateLimit(persona.id, toolName, scope, now);
+        if (!rateResult.ok) {
+            lastFailure = { reason: rateResult.reason, scope };
+            continue;
+        }
+        return { allowed: true, matchedScope: scope };
+    }
+    if (lastFailure) {
+        return { allowed: false, reason: lastFailure.reason, matchedScope: lastFailure.scope };
+    }
+    if (!anyToolMatch) {
+        return { allowed: false, reason: `no scope matched tool "${toolName}"` };
+    }
+    return { allowed: false, reason: 'permission denied' };
+}
+/**
+ * Throws PermissionDeniedError if canInvoke yields a denied verdict.
+ * Returns the verdict on success for callers that want to inspect matchedScope.
+ */
+export function enforce(grant, opts) {
+    const verdict = canInvoke(grant.persona, grant.toolName, grant.args, opts);
+    if (!verdict.allowed)
+        throw new PermissionDeniedError(grant, verdict);
+    return verdict;
+}
+/**
+ * Compose multiple personas into a single one.
+ * - id: joined with "+"
+ * - description: joined with "; "
+ * - scopes: concatenated (canInvoke iterates in order, so earliest wins ties)
+ * - maxBlastRadius: max over all inputs (undefined treated as 'none')
+ *
+ * Rate-limit state is keyed on the *resulting* persona's id, so merged
+ * personas have their own counter independent of the inputs.
+ */
+export function mergePersonas(...personas) {
+    if (personas.length === 0) {
+        return { id: 'empty', description: 'empty merged persona', scopes: [], maxBlastRadius: 'none' };
+    }
+    if (personas.length === 1)
+        return personas[0];
+    const id = personas.map((p) => p.id).join('+');
+    const description = personas.map((p) => p.description).join('; ');
+    const scopes = personas.flatMap((p) => p.scopes);
+    let cap = 'none';
+    for (const p of personas) {
+        if (p.maxBlastRadius)
+            cap = maxBlastRadius(cap, p.maxBlastRadius);
+    }
+    return { id, description, scopes, maxBlastRadius: cap };
+}
+/**
+ * Lookup helper. Throws on miss so callers fail loudly rather than silently
+ * proceeding without a scope.
+ */
+export function loadPersona(id, registry) {
+    const found = registry[id];
+    if (!found)
+        throw new Error(`unknown persona id "${id}"`);
+    return found;
+}
+//# sourceMappingURL=check.js.map

package/dist/futures/persona/index.d.ts

@@ -0,0 +1,5 @@
+export type { ArgRule, BlastRadius, PermissionGrant, Persona, Scope, Verdict, } from './types.js';
+export { BLAST_RADIUS_ORDER, PermissionDeniedError } from './types.js';
+export { canInvoke, enforce, mergePersonas, loadPersona } from './check.js';
+export { RESEARCHER, CODER, COMPUTER_USE, PERSONA_REGISTRY } from './registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/futures/persona/index.js

@@ -0,0 +1,5 @@
+// futures/persona — public surface.
+export { BLAST_RADIUS_ORDER, PermissionDeniedError } from './types.js';
+export { canInvoke, enforce, mergePersonas, loadPersona } from './check.js';
+export { RESEARCHER, CODER, COMPUTER_USE, PERSONA_REGISTRY } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/futures/persona/registry.d.ts

@@ -0,0 +1,22 @@
+import { Persona } from './types.js';
+/**
+ * Researcher: read-only research tools. Cannot mutate filesystem, repo, or
+ * external state. Web fetches and grep are fine; writes are not.
+ */
+export declare const RESEARCHER: Persona;
+/**
+ * Coder: read-write inside the workspace. Bash allowed but the most common
+ * destructive forms are denied via deny-pattern argRules. No force pushes.
+ * Rate limit on bash so a runaway loop can't burn 10k commands.
+ */
+export declare const CODER: Persona;
+/**
+ * Computer-use: explicit destructive opt-in. GUI tools that drive the user's
+ * physical desktop. Rate-limited so a hung loop can't spam clicks.
+ */
+export declare const COMPUTER_USE: Persona;
+/**
+ * Default registry. Add to this when wiring more personas.
+ */
+export declare const PERSONA_REGISTRY: Record<string, Persona>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/futures/persona/registry.js

@@ -0,0 +1,124 @@
+// futures/persona/registry — example personas. Hand-curated, not auto-generated.
+//
+// These three exist as concrete starting points for integration work; the
+// next session will wire them into permissions.ts. Until then they're
+// import-and-use values for tests and ad-hoc experimentation.
+/**
+ * Researcher: read-only research tools. Cannot mutate filesystem, repo, or
+ * external state. Web fetches and grep are fine; writes are not.
+ */
+export const RESEARCHER = {
+    id: 'researcher',
+    description: 'Read-only research and search tools. No filesystem writes, no shell execution.',
+    maxBlastRadius: 'read-only',
+    scopes: [
+        { toolPattern: 'read_file', blastRadius: 'read-only' },
+        { toolPattern: 'list_directory', blastRadius: 'read-only' },
+        { toolPattern: 'grep', blastRadius: 'read-only' },
+        { toolPattern: 'glob', blastRadius: 'read-only' },
+        { toolPattern: 'web_search', blastRadius: 'read-only' },
+        { toolPattern: 'papers_search', blastRadius: 'read-only' },
+        { toolPattern: 'kbot_search', blastRadius: 'read-only' },
+        { toolPattern: 'arxiv_search', blastRadius: 'read-only' },
+        { toolPattern: /^github_(read_file|repo_info|search|trending|activity|issues)$/, blastRadius: 'read-only' },
+    ],
+};
+/**
+ * Coder: read-write inside the workspace. Bash allowed but the most common
+ * destructive forms are denied via deny-pattern argRules. No force pushes.
+ * Rate limit on bash so a runaway loop can't burn 10k commands.
+ */
+export const CODER = {
+    id: 'coder',
+    description: 'Read-write code tools. Bash allowed but rm -rf and force-push denied. Bash 60/min.',
+    maxBlastRadius: 'sandboxed',
+    scopes: [
+        { toolPattern: 'read_file', blastRadius: 'read-only' },
+        { toolPattern: 'list_directory', blastRadius: 'read-only' },
+        { toolPattern: 'grep', blastRadius: 'read-only' },
+        { toolPattern: 'glob', blastRadius: 'read-only' },
+        { toolPattern: 'write_file', blastRadius: 'sandboxed' },
+        { toolPattern: 'edit_file', blastRadius: 'sandboxed' },
+        { toolPattern: 'multi_file_write', blastRadius: 'sandboxed' },
+        {
+            toolPattern: 'bash',
+            blastRadius: 'sandboxed',
+            argConstraints: {
+                // deny rm -rf at /, ~, or anywhere with force; deny sudo; deny curl|sh
+                command: {
+                    type: 'string',
+                    denyPattern: true,
+                    pattern: /(\brm\s+-[rRfF]+\s+(\/|~|\$HOME)|sudo\s+|curl\s+[^|]*\|\s*(sh|bash)|:\(\)\s*\{)/,
+                },
+            },
+            rateLimit: { max: 60, windowMs: 60_000 },
+        },
+        { toolPattern: /^git_(status|log|diff|branch|commit)$/, blastRadius: 'sandboxed' },
+        {
+            toolPattern: 'git_push',
+            blastRadius: 'sandboxed',
+            argConstraints: {
+                // forbid --force, --force-with-lease, -f
+                args: {
+                    type: 'string',
+                    denyPattern: true,
+                    pattern: /(^|\s)(--force(-with-lease)?|-f)(\s|$)/,
+                },
+            },
+        },
+        { toolPattern: /^npm_/, blastRadius: 'sandboxed' },
+        { toolPattern: /^pip_/, blastRadius: 'sandboxed' },
+    ],
+};
+/**
+ * Computer-use: explicit destructive opt-in. GUI tools that drive the user's
+ * physical desktop. Rate-limited so a hung loop can't spam clicks.
+ */
+export const COMPUTER_USE = {
+    id: 'computer-use',
+    description: 'Desktop control: mouse, keyboard, app launch. Destructive blast radius. 30/min.',
+    maxBlastRadius: 'destructive',
+    scopes: [
+        {
+            toolPattern: 'mouse_click',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        {
+            toolPattern: 'mouse_move',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        {
+            toolPattern: 'mouse_drag',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        {
+            toolPattern: 'keyboard_type',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        {
+            toolPattern: 'keyboard_shortcut',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        {
+            toolPattern: 'app_launch',
+            blastRadius: 'destructive',
+            rateLimit: { max: 30, windowMs: 60_000 },
+        },
+        { toolPattern: 'screenshot', blastRadius: 'read-only' },
+        { toolPattern: 'window_list', blastRadius: 'read-only' },
+    ],
+};
+/**
+ * Default registry. Add to this when wiring more personas.
+ */
+export const PERSONA_REGISTRY = {
+    researcher: RESEARCHER,
+    coder: CODER,
+    'computer-use': COMPUTER_USE,
+};
+//# sourceMappingURL=registry.js.map

package/dist/futures/persona/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Blast-radius hierarchy. Ordered from least to most dangerous.
+ * A Persona's maxBlastRadius caps the radius any of its scopes may target;
+ * mergePersonas() takes the maximum across inputs.
+ */
+export type BlastRadius = 'none' | 'read-only' | 'sandboxed' | 'destructive';
+export declare const BLAST_RADIUS_ORDER: readonly BlastRadius[];
+/**
+ * Constraint applied to a single tool argument by name.
+ * - `type` — required runtime type
+ * - `allowedValues` — enum of permitted literal values (when type === 'enum')
+ * - `pattern` — regex test for string args (rejected if it matches a
+ *   forbidden form; we use it as a *deny* pattern by convention — see check.ts)
+ * - `min` / `max` — numeric bounds (inclusive). For strings, applied to length.
+ */
+export interface ArgRule {
+    type: 'string' | 'number' | 'boolean' | 'enum';
+    allowedValues?: unknown[];
+    pattern?: RegExp;
+    /** When true, the regex acts as a *deny* pattern (match → reject). Defaults to false (must match). */
+    denyPattern?: boolean;
+    min?: number;
+    max?: number;
+}
+/**
+ * A single permission scope. Match against a tool name and a payload of args.
+ * - `toolPattern` — exact string match or RegExp test
+ * - `argConstraints` — keyed by argument name
+ * - `rateLimit` — sliding-window counter shared per (persona.id, toolName)
+ */
+export interface Scope {
+    toolPattern: string | RegExp;
+    argConstraints?: Record<string, ArgRule>;
+    rateLimit?: {
+        max: number;
+        windowMs: number;
+    };
+    /** Optional radius for this scope; cannot exceed Persona's maxBlastRadius. */
+    blastRadius?: BlastRadius;
+}
+/**
+ * Named, composable persona. `id` is the lookup key in the registry.
+ */
+export interface Persona {
+    id: string;
+    description: string;
+    scopes: Scope[];
+    maxBlastRadius?: BlastRadius;
+}
+export interface PermissionGrant {
+    persona: Persona;
+    toolName: string;
+    args: Record<string, unknown>;
+}
+export interface Verdict {
+    allowed: boolean;
+    reason?: string;
+    matchedScope?: Scope;
+}
+/**
+ * Thrown by enforce(). Carries the full verdict for upstream logging.
+ */
+export declare class PermissionDeniedError extends Error {
+    readonly verdict: Verdict;
+    readonly grant: PermissionGrant;
+    constructor(grant: PermissionGrant, verdict: Verdict);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/futures/persona/types.js

@@ -0,0 +1,28 @@
+// futures/persona/types — type-checked privilege scoping for tool invocation.
+//
+// A Persona is a named bundle of Scopes. A Scope binds a tool pattern to a
+// set of argument constraints, an optional rate limit, and is bounded by
+// the Persona's max blast radius. canInvoke() resolves a (persona, tool, args)
+// triple to a Verdict. enforce() turns a denied Verdict into a thrown error.
+//
+// Module is standalone — no integration into permissions.ts yet.
+export const BLAST_RADIUS_ORDER = [
+    'none',
+    'read-only',
+    'sandboxed',
+    'destructive',
+];
+/**
+ * Thrown by enforce(). Carries the full verdict for upstream logging.
+ */
+export class PermissionDeniedError extends Error {
+    verdict;
+    grant;
+    constructor(grant, verdict) {
+        super(`permission denied: persona=${grant.persona.id} tool=${grant.toolName} reason=${verdict.reason ?? 'no scope matched'}`);
+        this.name = 'PermissionDeniedError';
+        this.verdict = verdict;
+        this.grant = grant;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/futures/skill-graph/graph.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Skill graph — runtime ops.
+ *
+ * Pure functions over the SkillGraph data structure. Mutators return new
+ * instances rather than mutating in place; the underlying Maps and arrays
+ * are copied. Random walks use a seeded LCG for deterministic tests.
+ */
+import type { Edge, GraphPath, Scenario, Skill, SkillGraph } from './types.js';
+export declare function buildGraph(): SkillGraph;
+export declare function addSkill(g: SkillGraph, skill: Skill): SkillGraph;
+export declare function addScenario(g: SkillGraph, scenario: Scenario): SkillGraph;
+export declare function addEdge(g: SkillGraph, edge: Edge): SkillGraph;
+export interface SampleOptions {
+    start?: string;
+    maxLength?: number;
+    seed?: number;
+}
+export declare function samplePath(g: SkillGraph, opts?: SampleOptions): GraphPath;
+export declare function findPaths(g: SkillGraph, fromId: string, toId: string, maxDepth?: number): GraphPath[];
+export interface PathLengthStats {
+    min: number;
+    max: number;
+    avg: number;
+    p50: number;
+    p95: number;
+    samples: number;
+}
+export declare function pathLengthDistribution(g: SkillGraph, samples?: number, opts?: {
+    seed?: number;
+}): PathLengthStats;
+//# sourceMappingURL=graph.d.ts.map