@decibelsystems/tools 2.2.0-beta.0 → 3.1.0

package/dist/identity.js

@@ -0,0 +1,312 @@
+// ============================================================================
+// Acting identity — EPIC-0040, ADR-0011
+// ============================================================================
+// Who made this write?
+//
+// Until now, nothing could answer that. X-User-Key was accepted at the HTTP
+// boundary, threaded onto DispatchContext.userKey, and read by nobody
+// (ISS-0163). provenance had the only real actor modelling in the tree, and it
+// sat off to one side as an event log rather than as a field on the records
+// themselves. So attribution was anecdotal: 251 provenance events, and the
+// records they describe carry no author at all.
+//
+// This module is the single answer, for both transports. The rule from
+// ADR-0011 is that there is ONE resolver with TWO sources, never two
+// mechanisms:
+//
+//     daemon (http)  ->  X-User-Key, a Supabase JWT, giving user:<uuid>
+//     stdio          ->  config / git / $USER, giving human:<name>
+//
+// The stdio half is not a fallback for the unusual case. It is the majority
+// path: decibel-tools is registered as a stdio server, so every Claude Code
+// session writes in its own process, where no HTTP header can exist. A design
+// that only works in the daemon would miss nearly every write an agent makes.
+//
+// IDENTITY IS REFERENCED HERE AND RESOLVED IN HQ. Records store a prefixed id
+// and never a display name, so renaming someone in the roster never has to
+// rewrite history across fifteen repos. Rendering a name is the roster's job
+// (hq.resolve_ids), and when the roster is unreachable an id renders as
+// itself. That degradation is deliberate and is the reason the prefix carries
+// the information about whether resolution is even possible.
+// ============================================================================
+import { AsyncLocalStorage } from 'async_hooks';
+import { execSync } from 'child_process';
+// ============================================================================
+// The prefix vocabulary
+// ============================================================================
+// Agreed with the decibel-hq peer 2026-09-20 and pinned there as the shared
+// contract. Two prefixes name a human, and the difference between them is the
+// whole point rather than an inconsistency to be tidied away:
+//
+//     human:<name>   local. From git config or $USER. Always available, even
+//                    with no account, no network and no HQ. Unresolvable by
+//                    definition — there is nothing to resolve it against.
+//     user:<uuid>    roster. An auth.users id. Resolvable, revocable, and
+//                    stable across renames.
+//
+// A record is NEVER rewritten to upgrade a human: to a user:. The mapping
+// lives in HQ (hq.identity_claims), so a local identity that is later claimed
+// by a real account resolves correctly from then on without anything in git
+// changing. History stays as it was written.
+//
+// This is not hypothetical tidiness. The actor ids actually on disk in this
+// repo are already fragmented: `human:ben` and
+// `human:mediareason <brottler@gmail.com>` are the same person, differing only
+// by whether DECIBEL_ACTOR_ID happened to be set in that process.
+/** Roster-resolvable prefixes. These are the only ones hq.resolve_ids knows. */
+const ROSTER_PREFIXES = ['user', 'agent', 'team'];
+// The prefix -> kind map. `claude:` and the system aliases are here because
+// provenance has always accepted them and history contains them; dropping them
+// would reclassify existing events.
+const KIND_BY_PREFIX = {
+    user: 'user',
+    agent: 'agent',
+    team: 'team',
+    // A scope selector only (ADR-0014): it names the org a query is scoped to and
+    // is never an actor, an assignee or a team. HQ's resolve_ids does not know it,
+    // so it is not in ROSTER_PREFIXES.
+    org: 'org',
+    // An outside collaborator (a client) invited to one project in HQ
+    // (decibel-hq ADR-0015, tools ISS-0212). The value is the hq.project_grants
+    // id, NOT an auth uid: the grant exists from the moment Ben invites someone,
+    // before they ever sign in, and revoking it ends their access. HQ renders
+    // it from the grant's display_name; resolve_ids does not know it, so it is
+    // not a roster prefix.
+    guest: 'guest',
+    human: 'human',
+    ai: 'ai',
+    claude: 'ai',
+    system: 'system',
+    hook: 'system',
+    automation: 'system',
+};
+const ACTOR_TYPE_BY_KIND = {
+    user: 'human',
+    human: 'human',
+    agent: 'ai',
+    ai: 'ai',
+    system: 'system',
+    // A team is never an actor (see assertActor), but the map must be total so
+    // that a caller who classifies one anyway gets something rather than
+    // undefined. Reaching this value means a check was skipped upstream.
+    team: 'human',
+    // Same as team: never an actor (assertActor rejects it); present for totality.
+    org: 'human',
+    // A person outside the org. Answers asks, so it can stand as an actor.
+    guest: 'human',
+};
+/**
+ * Split a prefixed id. Returns null for anything without a recognised prefix.
+ *
+ * Deliberately lenient about the VALUE: `human:mediareason <brottler@gmail.com>`
+ * is a real id in this repo's history — a git ident string, spaces, angle
+ * brackets, an embedded email and all. Nothing here may split, slugify or
+ * normalise it, because doing so would silently rewrite 202 existing events.
+ */
+export function parseIdentity(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const idx = trimmed.indexOf(':');
+    if (idx <= 0)
+        return null;
+    const prefix = trimmed.slice(0, idx).toLowerCase();
+    const value = trimmed.slice(idx + 1);
+    if (!value)
+        return null;
+    const kind = KIND_BY_PREFIX[prefix];
+    if (!kind)
+        return null;
+    return {
+        raw: trimmed,
+        prefix,
+        value,
+        kind,
+        resolvable: ROSTER_PREFIXES.includes(prefix),
+    };
+}
+/**
+ * The coarse actor type for an id. This is the canonical implementation —
+ * provenance's own classification defers to it so the two cannot drift.
+ *
+ * Unknown prefixes fall through to 'human', preserving the behaviour
+ * provenance has always had. That fall-through is safe ONLY because a `team:`
+ * id is rejected before it can reach an actor position; see assertActor.
+ */
+export function actorTypeOf(raw) {
+    const parsed = parseIdentity(raw);
+    if (!parsed)
+        return 'human';
+    return ACTOR_TYPE_BY_KIND[parsed.kind];
+}
+// ============================================================================
+// Write-side validation
+// ============================================================================
+// Both rules below come from the pinned contract, and both are enforced by
+// REJECTING rather than by reclassifying. A write that means something the
+// system cannot represent should fail where it is made, not be quietly turned
+// into a different write that happens to be representable.
+/** Prefixes legal in an actor or assignee position: a person or an agent. */
+const ACTOR_PREFIXES = new Set(['user', 'human', 'guest', 'agent', 'ai', 'claude', 'system', 'hook', 'automation']);
+export class IdentityError extends Error {
+}
+/**
+ * Assert that `raw` may stand where an actor or an assignee is expected.
+ *
+ * A `team:` id is specifically rejected here. Assigning to a team is what the
+ * `team` FIELD expresses; keeping assignee singular is what keeps a team a
+ * lens rather than an owner, which is Ben's decision in ADR-0011. Without this
+ * check, `team:<uuid>` would classify as 'human' through the fall-through in
+ * actorTypeOf and be recorded as a person.
+ */
+export function assertActor(raw) {
+    const parsed = parseIdentity(raw);
+    if (!parsed) {
+        throw new IdentityError(`"${raw}" is not a valid identity. Expected a prefixed id such as ` +
+            `user:<uuid>, agent:<uuid> or human:<name>.`);
+    }
+    if (parsed.kind === 'team') {
+        throw new IdentityError(`"${raw}" names a team, and a team cannot be an assignee. Put the team in the ` +
+            `\`team\` field instead — assignee is a single person or agent.`);
+    }
+    if (parsed.kind === 'org') {
+        throw new IdentityError(`"${raw}" names an org, and an org cannot be an actor or an assignee. An org ` +
+            `id only selects the scope of a query.`);
+    }
+    if (!ACTOR_PREFIXES.has(parsed.prefix)) {
+        throw new IdentityError(`"${raw}" is not valid in an assignee position.`);
+    }
+    return parsed;
+}
+/** Assert that `raw` may stand in a `team` field. Only `team:` ids qualify. */
+export function assertTeam(raw) {
+    const parsed = parseIdentity(raw);
+    if (!parsed || parsed.kind !== 'team') {
+        throw new IdentityError(`"${raw}" is not a team id. Expected team:<uuid>. Team ids are minted by HQ; ` +
+            `a slug or a free-text name is not accepted, because it would have to be ` +
+            `migrated to a uuid later.`);
+    }
+    return parsed;
+}
+/**
+ * Read the `sub` claim out of a Supabase JWT without verifying it.
+ *
+ * Returns null on anything malformed. This must never throw: attribution is
+ * not worth failing a write over, and a caller with a broken token should end
+ * up attributed to their local identity rather than blocked.
+ */
+function subjectOfUnverifiedJwt(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
+        const claims = JSON.parse(json);
+        return typeof claims.sub === 'string' && claims.sub ? claims.sub : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Memoised because resolveActingIdentity runs on EVERY dispatch, and this
+// shells out twice. `undefined` means not yet looked up; `null` means looked
+// up and absent — the distinction is what stops a machine without git config
+// from paying for two failed execSync calls per tool call.
+let gitUserCache;
+/**
+ * The git identity as `name <email>`, or the bare name, or null.
+ *
+ * This is the canonical implementation; provenance defers to it so the two
+ * cannot drift. It is also why the ids on disk look the way they do — the
+ * angle-bracket form is a git ident string, not a handle, and parseIdentity
+ * preserves it verbatim for that reason.
+ */
+export function gitUserIdent() {
+    if (gitUserCache !== undefined)
+        return gitUserCache;
+    try {
+        const opts = { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] };
+        const name = execSync('git config user.name', opts).trim();
+        const email = execSync('git config user.email', opts).trim();
+        gitUserCache = name && email ? `${name} <${email}>` : name || null;
+    }
+    catch {
+        gitUserCache = null;
+    }
+    return gitUserCache;
+}
+/** Test seam: drop the memoised git identity. */
+export function resetGitUserCache() {
+    gitUserCache = undefined;
+}
+/**
+ * The acting identity for this call.
+ *
+ * Order: an explicit DECIBEL_ACTOR_ID always wins, because it is the only way
+ * an operator can state who they are; then the JWT; then git; then the OS
+ * user. The env var outranks the header deliberately — a machine configured to
+ * say who it is should not be overridden by whatever token a caller presents.
+ */
+export function resolveActingIdentity(ctx, sources = {}) {
+    const env = sources.env ?? process.env;
+    const explicit = env.DECIBEL_ACTOR_ID?.trim();
+    const explicitParsed = explicit ? parseIdentity(explicit) : null;
+    // A team or an org cannot act. Ignore such a value and fall through to the
+    // next source rather than recording a team or an org as the author.
+    const nonActor = explicitParsed?.kind === 'team' || explicitParsed?.kind === 'org';
+    if (explicit && !nonActor) {
+        if (explicitParsed)
+            return { id: explicitParsed.raw, parsed: explicitParsed, source: 'env', verified: false };
+        // An unprefixed DECIBEL_ACTOR_ID is a configuration mistake, not a reason
+        // to lose the operator's intent. Treat it as the local name they meant.
+        const coerced = parseIdentity(`human:${explicit}`);
+        return { id: coerced.raw, parsed: coerced, source: 'env', verified: false };
+    }
+    if (ctx?.userKey) {
+        const sub = subjectOfUnverifiedJwt(ctx.userKey);
+        if (sub) {
+            const parsed = parseIdentity(`user:${sub}`);
+            return { id: parsed.raw, parsed, source: 'header', verified: false };
+        }
+        // Fall through. A malformed token attributes to the local identity rather
+        // than to nobody, and rather than failing the write.
+    }
+    const gitUser = (sources.gitUser ?? gitUserIdent)();
+    if (gitUser) {
+        const parsed = parseIdentity(`human:${gitUser}`);
+        return { id: parsed.raw, parsed, source: 'git', verified: false };
+    }
+    const osUser = env.USER || env.USERNAME || 'unknown';
+    const parsed = parseIdentity(`human:${osUser}`);
+    return { id: parsed.raw, parsed, source: 'os', verified: false };
+}
+const storage = new AsyncLocalStorage();
+/**
+ * Run `fn` with `identity` as the acting identity. Nested calls keep the
+ * outermost identity: a tool that dispatches another tool is still the same
+ * person acting, and re-deriving it inside would let a delegated call
+ * attribute itself to the daemon's local user.
+ */
+export function withIdentity(identity, fn) {
+    const existing = storage.getStore();
+    if (existing?.identity)
+        return fn();
+    return storage.run({ identity }, fn);
+}
+/**
+ * The acting identity for the current dispatch, if a scope is open.
+ *
+ * Returns undefined outside a scope rather than inventing an identity. A
+ * writer that gets undefined should omit the field, not guess — an absent
+ * author is honest, and a wrong one is not.
+ */
+export function currentIdentity() {
+    return storage.getStore()?.identity;
+}
+/** The id to stamp, or undefined outside a dispatch scope. */
+export function currentActorId() {
+    return storage.getStore()?.identity?.id;
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}

package/dist/kernel.d.ts

@@ -1,5 +1,6 @@
 import type { ToolSpec, ToolResult } from './tools/types.js';
 import type { FacadeSpec, DetailTier, McpToolDefinition } from './facades/types.js';
+import { type CircuitSnapshot } from './runtime/circuitBreaker.js';
 /**
  * Optional context threaded through every dispatch call.
  * This is plumbing, not policy — the kernel passes it to handlers
@@ -20,6 +21,15 @@ export interface DispatchContext {
     allowedFacades?: string[];
     /** License tier — when set, pro facades are rejected for 'core' tier */
     tier?: 'core' | 'pro' | 'apps';
+    /**
+     * Which transport carried this call. Set by the adapter, never by the caller.
+     * 'http' rejects facades marked localOnly — see FacadeSpec.localOnly.
+     *
+     * Unset means stdio: a context arriving without a transport came from an
+     * in-process caller, and defaulting the ABSENT case to 'http' would break
+     * every existing direct kernel consumer. The HTTP adapters set it explicitly.
+     */
+    transport?: 'stdio' | 'http';
     /** Engagement mode: 'suggest' | 'curate' | 'compose' */
     engagementMode?: string;
     /** Identity of the calling user (Supabase access token / JWT, via X-User-Key) */
@@ -29,6 +39,22 @@ export interface DispatchContext {
     /** Request correlation ID (crypto.randomUUID) — set by client, threaded through events */
     requestId?: string;
 }
+/**
+ * What the last createKernel() call loaded, and what it refused. Surfaced on
+ * /health so a rejected extension is visible without reading the daemon log.
+ */
+export declare function getExtensionDiagnostics(): {
+    loaded: Array<{
+        name: string;
+        version: string;
+        tier: string;
+        facades: string[];
+    }>;
+    rejected: Array<{
+        entry: string;
+        reason: string;
+    }>;
+};
 export interface DispatchEvent {
     type: 'dispatch' | 'result' | 'error';
     facade?: string;
@@ -54,6 +80,15 @@ export interface BatchResult {
     action: string;
     result?: ToolResult;
     error?: string;
+    /**
+     * Machine-readable failure kind. Present only for STRUCTURAL failures — the
+     * call never ran because nothing by that name is registered. A call that ran
+     * and failed carries its failure in `result.isError` instead, which is a
+     * different thing and must stay distinguishable: "this facade does not exist
+     * here" and "this action returned an error" need different reactions from a
+     * caller, and only the first is a configuration problem.
+     */
+    code?: 'UNKNOWN_FACADE';
     duration_ms: number;
 }
 export interface ToolKernel {
@@ -81,11 +116,21 @@ export interface ToolKernel {
      * Get MCP tool definitions for the tools/list response.
      * Returns facade definitions filtered by detail tier.
      */
-    getMcpToolDefinitions(tier?: DetailTier): McpToolDefinition[];
+    getMcpToolDefinitions(tier?: DetailTier, opts?: {
+        transport?: 'stdio' | 'http';
+    }): McpToolDefinition[];
     /** Subscribe to dispatch events (dispatch, result, error) */
     on(event: string, listener: (evt: DispatchEvent) => void): void;
     /** Unsubscribe from dispatch events (for SSE cleanup) */
     off(event: string, listener: (evt: DispatchEvent) => void): void;
+    /**
+     * Circuits that are open or accumulating faults, keyed by facade.
+     * Empty object means every facade is healthy. Surfaced on /health so a
+     * degraded dependency is visible without reading the dispatch log.
+     */
+    circuitSnapshot(): Record<string, CircuitSnapshot>;
+    /** Force a circuit closed (operator escape hatch, and test hygiene). */
+    resetCircuit(key?: string): void;
     /** Total internal tool count */
     toolCount: number;
     /** Total facade count */

package/dist/kernel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../src/kernel.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../src/kernel.ts"],"names":[],"mappings":"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"}