@kernel.chat/kbot 4.0.0 → 4.1.0

package/dist/futures/latent-state/envelope.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Latent-state envelope — runtime helpers.
+ * Pure functions over `LatentEnvelope`. Node `crypto` (sha256) for hashing.
+ */
+import type { LatentEnvelope, ProvenanceEntry } from './types.js';
+/** JSON.stringify with deterministic key order (Object.keys().sort()). */
+export declare function stableStringify(value: unknown): string;
+export interface CreateEnvelopeOpts {
+    from: string;
+    to: string;
+    text?: string;
+    structured?: Record<string, unknown>;
+    createdAt?: string;
+    note?: string;
+}
+/**
+ * Build a fresh envelope. Auto-derives `kind`, stamps `createdAt`, seeds
+ * provenance with a single step from `opts.from`, and computes `contentHash`.
+ */
+export declare function createEnvelope(opts: CreateEnvelopeOpts): LatentEnvelope;
+/** JSON-serialize an envelope with stable key order. */
+export declare function serialize(env: LatentEnvelope): string;
+/** Parse, validate shape, recompute hash, throw if mismatch. */
+export declare function deserialize(s: string): LatentEnvelope;
+/** True iff stored `contentHash` matches a fresh hash of the body. */
+export declare function verifyHash(env: LatentEnvelope): boolean;
+/** Append a provenance step and rehash. Returns a new envelope. */
+export declare function withProvenance(env: LatentEnvelope, entry: Omit<ProvenanceEntry, 'step'> & {
+    step?: number;
+}): LatentEnvelope;
+/**
+ * Combine two envelopes from the same from/to pair.
+ * - text: a + '\n' + b
+ * - structured: shallow merge with one-level deep-merge for plain objects
+ * - provenance: a then b, renumbered sequentially
+ * - createdAt: fresh ISO timestamp; contentHash: recomputed
+ */
+export declare function merge(a: LatentEnvelope, b: LatentEnvelope): LatentEnvelope;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/futures/latent-state/envelope.js

@@ -0,0 +1,178 @@
+/**
+ * Latent-state envelope — runtime helpers.
+ * Pure functions over `LatentEnvelope`. Node `crypto` (sha256) for hashing.
+ */
+import { createHash } from 'node:crypto';
+/** JSON.stringify with deterministic key order (Object.keys().sort()). */
+export function stableStringify(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    const obj = value;
+    const out = {};
+    for (const key of Object.keys(obj).sort())
+        out[key] = canonicalize(obj[key]);
+    return out;
+}
+function hashableBody(env) {
+    return {
+        version: env.version, from: env.from, to: env.to, kind: env.kind,
+        text: env.text, structured: env.structured,
+        provenance: env.provenance, createdAt: env.createdAt,
+    };
+}
+function computeHash(env) {
+    return createHash('sha256').update(stableStringify(hashableBody(env))).digest('hex');
+}
+function classify(text, structured) {
+    if (text !== undefined && structured !== undefined)
+        return 'mixed';
+    if (structured !== undefined)
+        return 'structured';
+    return 'text';
+}
+/**
+ * Build a fresh envelope. Auto-derives `kind`, stamps `createdAt`, seeds
+ * provenance with a single step from `opts.from`, and computes `contentHash`.
+ */
+export function createEnvelope(opts) {
+    const kind = classify(opts.text, opts.structured);
+    const createdAt = opts.createdAt ?? new Date().toISOString();
+    const provenance = [
+        {
+            step: 1,
+            agent: opts.from,
+            ts: createdAt,
+            ...(opts.note !== undefined ? { note: opts.note } : {}),
+        },
+    ];
+    const body = {
+        version: 1,
+        from: opts.from,
+        to: opts.to,
+        kind,
+        ...(opts.text !== undefined ? { text: opts.text } : {}),
+        ...(opts.structured !== undefined ? { structured: opts.structured } : {}),
+        provenance,
+        createdAt,
+    };
+    return { ...body, contentHash: computeHash(body) };
+}
+/** JSON-serialize an envelope with stable key order. */
+export function serialize(env) {
+    return stableStringify(env);
+}
+/** Parse, validate shape, recompute hash, throw if mismatch. */
+export function deserialize(s) {
+    let raw;
+    try {
+        raw = JSON.parse(s);
+    }
+    catch (err) {
+        throw new Error(`latent-state: invalid JSON: ${err.message}`);
+    }
+    const env = assertShape(raw);
+    if (!verifyHash(env)) {
+        throw new Error('latent-state: contentHash mismatch — envelope tampered');
+    }
+    return env;
+}
+function assertShape(raw) {
+    if (!raw || typeof raw !== 'object')
+        throw new Error('latent-state: envelope must be an object');
+    const o = raw;
+    if (o.version !== 1)
+        throw new Error(`latent-state: unsupported version ${String(o.version)}`);
+    if (typeof o.from !== 'string' || typeof o.to !== 'string')
+        throw new Error('latent-state: from/to must be strings');
+    if (o.kind !== 'text' && o.kind !== 'structured' && o.kind !== 'mixed')
+        throw new Error(`latent-state: invalid kind ${String(o.kind)}`);
+    if (typeof o.createdAt !== 'string' || typeof o.contentHash !== 'string')
+        throw new Error('latent-state: createdAt/contentHash must be strings');
+    if (!Array.isArray(o.provenance) || o.provenance.length === 0)
+        throw new Error('latent-state: provenance must be a non-empty array');
+    return o;
+}
+/** True iff stored `contentHash` matches a fresh hash of the body. */
+export function verifyHash(env) {
+    const { contentHash, ...body } = env;
+    return computeHash(body) === contentHash;
+}
+/** Append a provenance step and rehash. Returns a new envelope. */
+export function withProvenance(env, entry) {
+    const nextStep = entry.step ?? Math.max(0, ...env.provenance.map((p) => p.step)) + 1;
+    const provenance = [
+        ...env.provenance,
+        {
+            step: nextStep,
+            agent: entry.agent,
+            ts: entry.ts,
+            ...(entry.note !== undefined ? { note: entry.note } : {}),
+        },
+    ];
+    const { contentHash: _drop, ...rest } = { ...env, provenance };
+    void _drop;
+    return { ...rest, contentHash: computeHash(rest) };
+}
+/**
+ * Combine two envelopes from the same from/to pair.
+ * - text: a + '\n' + b
+ * - structured: shallow merge with one-level deep-merge for plain objects
+ * - provenance: a then b, renumbered sequentially
+ * - createdAt: fresh ISO timestamp; contentHash: recomputed
+ */
+export function merge(a, b) {
+    if (a.from !== b.from || a.to !== b.to) {
+        throw new Error('latent-state: cannot merge envelopes with different from/to');
+    }
+    const text = mergeText(a.text, b.text);
+    const structured = mergeStructured(a.structured, b.structured);
+    const kind = classify(text, structured);
+    const provenance = [...a.provenance, ...b.provenance].map((p, i) => ({ ...p, step: i + 1 }));
+    const body = {
+        version: 1,
+        from: a.from,
+        to: a.to,
+        kind,
+        ...(text !== undefined ? { text } : {}),
+        ...(structured !== undefined ? { structured } : {}),
+        provenance,
+        createdAt: new Date().toISOString(),
+    };
+    return { ...body, contentHash: computeHash(body) };
+}
+function mergeText(a, b) {
+    if (a === undefined && b === undefined)
+        return undefined;
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return `${a}\n${b}`;
+}
+function mergeStructured(a, b) {
+    if (!a && !b)
+        return undefined;
+    if (!a)
+        return { ...b };
+    if (!b)
+        return { ...a };
+    const out = { ...a };
+    for (const k of Object.keys(b)) {
+        const av = a[k], bv = b[k];
+        if (av && bv &&
+            typeof av === 'object' && typeof bv === 'object' &&
+            !Array.isArray(av) && !Array.isArray(bv)) {
+            out[k] = { ...av, ...bv };
+        }
+        else {
+            out[k] = bv;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=envelope.js.map

package/dist/futures/latent-state/index.d.ts

@@ -0,0 +1,5 @@
+/** Latent-state envelope — public surface. */
+export type { AgentTransfer, EnvelopeKind, LatentEnvelope, ProvenanceEntry, } from './types.js';
+export { createEnvelope, deserialize, merge, serialize, stableStringify, verifyHash, withProvenance, } from './envelope.js';
+export type { CreateEnvelopeOpts } from './envelope.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/futures/latent-state/index.js

@@ -0,0 +1,3 @@
+/** Latent-state envelope — public surface. */
+export { createEnvelope, deserialize, merge, serialize, stableStringify, verifyHash, withProvenance, } from './envelope.js';
+//# sourceMappingURL=index.js.map

package/dist/futures/latent-state/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Latent-state envelope — type definitions.
+ *
+ * Maps onto "Recursive Multi-Agent Systems" (Stanford/UIUC/NVIDIA/MIT,
+ * arXiv:2604.25917). Today most inter-agent handoffs are plain text. As
+ * models gain native structured-state IO, the harness should already be
+ * carrying typed envelopes so the upgrade path is a payload swap, not an
+ * interface change.
+ *
+ * Runtime lives in `envelope.ts`.
+ */
+/** One step in the chain of custody. */
+export interface ProvenanceEntry {
+    step: number;
+    agent: string;
+    ts: string;
+    note?: string;
+}
+/**
+ * Payload discriminator.
+ *  - 'text'       — text only (today's common case)
+ *  - 'structured' — structured payload only (latent-state native)
+ *  - 'mixed'      — both present
+ */
+export type EnvelopeKind = 'text' | 'structured' | 'mixed';
+/**
+ * `contentHash` is sha256 over a canonical JSON serialization of the body
+ * (every field except contentHash itself). Used by `verifyHash` to detect
+ * tampering and by `merge` to derive fresh hashes after combining.
+ */
+export interface LatentEnvelope {
+    version: 1;
+    from: string;
+    to: string;
+    kind: EnvelopeKind;
+    text?: string;
+    structured?: Record<string, unknown>;
+    provenance: ProvenanceEntry[];
+    createdAt: string;
+    contentHash: string;
+}
+/** Wraps an envelope for transport. `ackToken` reserved for future ack flows. */
+export interface AgentTransfer {
+    envelope: LatentEnvelope;
+    ackToken?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/futures/latent-state/types.js

@@ -0,0 +1,13 @@
+/**
+ * Latent-state envelope — type definitions.
+ *
+ * Maps onto "Recursive Multi-Agent Systems" (Stanford/UIUC/NVIDIA/MIT,
+ * arXiv:2604.25917). Today most inter-agent handoffs are plain text. As
+ * models gain native structured-state IO, the harness should already be
+ * carrying typed envelopes so the upgrade path is a payload swap, not an
+ * interface change.
+ *
+ * Runtime lives in `envelope.ts`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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