brainclaw 1.14.0 → 1.16.0

package/dist/commands/mcp-write-support.js

@@ -0,0 +1,367 @@
+/**
+ * Shared MCP write-path support helpers.
+ *
+ * Extracted mechanically from mcp.ts (pln#622 PR3a): identity resolution and
+ * trust gating shared by every write-tool domain (coordination, sequences,
+ * steps, canonical grammar, …). mcp.ts re-exports the historical test surface
+ * (`__resetConnectionPrincipalForTests`, `PinnedConnectionPrincipal`).
+ *
+ * Import rule (pln#622 PR1 guard): this module must never import ./mcp.js.
+ *
+ * @module
+ */
+import { AgentIdentityResolutionError, AgentTrustError, findAgentIdentityById, findAgentIdentityByName, normalizeAgentName, requireMinimumTrustLevel, requireRegisteredAgentIdentity, resolveCurrentAgentIdentity, resolveOrAutoRegisterAgentIdentity, } from '../core/agent-registry.js';
+import { loadClaim } from '../core/claims.js';
+import { loadConfig } from '../core/config.js';
+import { isObserverMode } from '../core/observer-mode.js';
+import { buildOperationalIdentity, loadCurrentSession, loadSessionById, saveCurrentSession } from '../core/identity.js';
+import { scanText } from '../core/security.js';
+import { toolResponse } from './mcp-contract.js';
+let principalCache;
+/** Test hook — the principal is otherwise pinned for the process lifetime. */
+export function __resetConnectionPrincipalForTests() {
+    principalCache = undefined;
+}
+/**
+ * Resolve the connection principal. The MCP server is one process per
+ * connection, so a process-level pin IS the per-connection pin; the cache key
+ * guards the identity-bearing env vars so in-process test harnesses that
+ * switch agents between calls re-resolve instead of leaking the first pin.
+ */
+export function resolveConnectionPrincipal(cwd, sessionId) {
+    const env = process.env;
+    const key = [
+        env.BRAINCLAW_CLAIM_ID ?? '', env.BRAINCLAW_AGENT_ID ?? '',
+        env.BRAINCLAW_AGENT_NAME ?? '', env.BRAINCLAW_AGENT ?? '',
+        cwd ?? '', sessionId ?? '',
+    ].join('|');
+    if (principalCache && principalCache.key === key)
+        return principalCache.value;
+    let value;
+    // 1. Assignment binding: a dispatched worker carries BRAINCLAW_CLAIM_ID; the
+    //    claim names the identity the coordinator dispatched — authoritative.
+    const claimId = env.BRAINCLAW_CLAIM_ID?.trim();
+    if (claimId) {
+        try {
+            const claim = loadClaim(claimId, cwd);
+            const identity = (claim.agent_id ? findAgentIdentityById(claim.agent_id, cwd) : undefined)
+                ?? findAgentIdentityByName(claim.agent, cwd);
+            if (identity) {
+                value = {
+                    agent_name: identity.agent_name,
+                    agent_id: identity.agent_id,
+                    session_id: claim.session_id ?? sessionId,
+                    pid: process.pid,
+                    source: 'claim_binding',
+                };
+            }
+        }
+        catch { /* claim may not exist in this store — fall through */ }
+    }
+    // 2. Server-side detection (env-pinned or detected REGISTERED identity —
+    //    read-only since pln#562 step 2, never mints).
+    if (!value) {
+        const identity = resolveCurrentAgentIdentity(cwd);
+        if (identity) {
+            value = {
+                agent_name: identity.agent_name,
+                agent_id: identity.agent_id,
+                session_id: sessionId,
+                pid: process.pid,
+                source: 'server_detection',
+            };
+        }
+    }
+    principalCache = { key, value };
+    return value;
+}
+export function resolveMutationIdentity(args, fields, cwd, sessionId) {
+    try {
+        const explicitName = typeof args[fields.nameField] === 'string' ? String(args[fields.nameField]) : undefined;
+        const explicitId = typeof args[fields.idField] === 'string' ? String(args[fields.idField]) : undefined;
+        // pln#562 step 3 — pinned connection principal. When the server resolved
+        // an authenticated principal, caller args are verified against it:
+        // matching/absent args → principal; mismatching args → curator-only
+        // explicit override, otherwise the mismatch is REJECTED loudly. Silently
+        // re-attributing a spoofed/mistaken identity to the principal would hide
+        // caller bugs — fail-loud is the contract (mcp-protocol.test 'rejects
+        // unregistered identities and mismatched id/name pairs').
+        const principal = resolveConnectionPrincipal(cwd, sessionId);
+        if (principal) {
+            // Re-load per call (cheap) so trust changes propagate mid-connection;
+            // the BINDING (who you are) stays pinned.
+            const principalDoc = findAgentIdentityById(principal.agent_id, cwd);
+            if (principalDoc) {
+                const mismatch = (explicitName !== undefined && normalizeAgentName(explicitName) !== normalizeAgentName(principal.agent_name))
+                    || (explicitId !== undefined && explicitId !== principal.agent_id);
+                if (!mismatch) {
+                    return { identity: principalDoc };
+                }
+                if ((principalDoc.trust_level ?? 'contributor') === 'curator') {
+                    return {
+                        identity: requireRegisteredAgentIdentity({
+                            agentName: explicitName,
+                            agentId: explicitId,
+                            cwd,
+                            allowCurrent: true,
+                            allowEnv: true,
+                        }),
+                    };
+                }
+                return {
+                    error: {
+                        kind: 'identity_error',
+                        message: `Caller-supplied identity (agent=${explicitName ?? '<none>'}, agentId=${explicitId ?? '<none>'}) does not match the pinned connection principal '${principal.agent_name}' (${principal.agent_id}). Omit the identity args, or have a curator perform the override.`,
+                    },
+                };
+            }
+        }
+        // No pinned principal (unregistered connection): legacy chain.
+        // Session-pinned identity: if no explicit agent in args, use the session's pinned agent
+        let agentName = explicitName;
+        if (!agentName && sessionId) {
+            const session = loadSessionById(sessionId, cwd);
+            if (session?.agent) {
+                agentName = session.agent;
+            }
+        }
+        return {
+            identity: requireRegisteredAgentIdentity({
+                agentName,
+                agentId: explicitId,
+                cwd,
+                allowCurrent: true,
+                allowEnv: true,
+            }),
+        };
+    }
+    catch (error) {
+        if (error instanceof AgentIdentityResolutionError) {
+            return {
+                error: {
+                    kind: error.kind,
+                    message: error.message,
+                    details: error.details,
+                },
+            };
+        }
+        return {
+            error: {
+                kind: 'identity_error',
+                message: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+}
+export function ensureTrust(args, fields, level, cwd, sessionId) {
+    const resolved = resolveMutationIdentity(args, fields, cwd, sessionId);
+    if ('error' in resolved) {
+        return resolved;
+    }
+    try {
+        requireMinimumTrustLevel(resolved.identity, level);
+        return resolved;
+    }
+    catch (error) {
+        if (error instanceof AgentTrustError) {
+            return {
+                error: {
+                    kind: error.kind,
+                    message: error.message,
+                    details: error.details,
+                },
+            };
+        }
+        return {
+            error: {
+                kind: 'trust_error',
+                message: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+}
+export function explicitSessionIdFromEnv() {
+    return process.env.BRAINCLAW_SESSION_ID?.trim()
+        || process.env.OPENCLAW_SESSION_ID?.trim()
+        || process.env.CLAUDE_SESSION_ID?.trim()
+        || process.env.COPILOT_SESSION_ID?.trim();
+}
+export function projectInfoForCwd(cwd) {
+    try {
+        const config = loadConfig(cwd);
+        return { path: cwd, name: config.project_name };
+    }
+    catch {
+        return { path: cwd };
+    }
+}
+/**
+ * Resolve the agent identity for canonical-grammar mutation verbs
+ * (bclaw_create/update/remove/transition), so handlers can auto-fill required
+ * fields (e.g. plan.author) instead of letting the create land on disk with a
+ * missing field — which would then be silently GC'd by the state sync loop
+ * (see fix plan pln_5f44426c).
+ *
+ * pln#562 step 3 — a write that would create a record with a missing/'unknown'
+ * author must never be silent (that produced records that passed creation but
+ * were schema-invalid on read and silently GC'd from disk).
+ *
+ * pln#608 — extended with auto-repair: when the caller has no session but a
+ * derivable agent name (arg / $BRAINCLAW_AGENT_NAME / detected AI agent),
+ * fall through to `resolveOrAutoRegisterAgentIdentity` and materialize the
+ * session via `buildOperationalIdentity({ persistImplicitSession: true })`
+ * (same mechanic as switchProject:86-106 and session-start). The freshly-
+ * created session is tagged `auto_created` so aggressive harvesting can
+ * distinguish it from operator sessions (pln#602). The caller receives
+ * `auto_repair` and surfaces it as a warning — never silent.
+ *
+ * KEEP (still a hard error, doctrine boundary): the identity is ambiguous
+ * (no name in args, no env signal, no detectable agent). We do not invent
+ * an identity — invoke intent is unclear and the write would misattribute.
+ */
+export function resolveCanonicalAuthor(args, cwd, connectionSessionId) {
+    const resolved = resolveMutationIdentity(args, { nameField: 'agent', idField: 'agentId' }, cwd, connectionSessionId);
+    if ('identity' in resolved && resolved.identity) {
+        return {
+            agent_name: resolved.identity.agent_name,
+            agent_id: resolved.identity.agent_id,
+        };
+    }
+    const strictError = 'error' in resolved && resolved.error ? resolved.error : undefined;
+    // KEEP (doctrine boundary): a pinned principal that rejected the caller args
+    // is a SPOOF/MISMATCH, not an ambiguous first-write. Never auto-repair over
+    // it — silently re-attributing would defeat pln#562 step 3. The strict error
+    // already carries the pointer to a curator override.
+    if (resolveConnectionPrincipal(cwd, connectionSessionId)) {
+        throw new Error(`cannot resolve mutation author: ${strictError?.message ?? 'principal mismatch'}`);
+    }
+    // Observer processes are read-only dashboards/inspectors. Even when an env
+    // variable leaks an agent name into the observer process, canonical writes
+    // must not use the auto-repair path because it can mint identity/session
+    // state as a side effect.
+    if (isObserverMode()) {
+        throw new Error(`cannot resolve mutation author: ${strictError?.message ?? 'observer mode cannot auto-repair identity/session state'}`);
+    }
+    const explicitName = typeof args.agent === 'string' ? args.agent : undefined;
+    const explicitId = typeof args.agentId === 'string' ? args.agentId : undefined;
+    // resolveOrAutoRegisterAgentIdentity's fall-through helper only reads
+    // BRAINCLAW_AGENT / OPENCLAW_AGENT. resolveCurrentAgentIdentity also honors
+    // BRAINCLAW_AGENT_NAME, and dispatched workers set both. Normalize here so
+    // an env-declared name is a first-class signal to the auto-repair path.
+    const envAgentName = explicitName
+        ?? (process.env.BRAINCLAW_AGENT_NAME?.trim() || undefined)
+        ?? (process.env.BRAINCLAW_AGENT?.trim() || undefined);
+    let identity;
+    let autoRegistered;
+    try {
+        const outcome = resolveOrAutoRegisterAgentIdentity({
+            agentName: envAgentName,
+            agentId: explicitId,
+            cwd,
+            allowCurrent: true,
+            allowEnv: true,
+        });
+        identity = outcome.identity;
+        autoRegistered = outcome.auto_registered;
+    }
+    catch (err) {
+        // Genuine ambiguity — no derivable name. Stays a hard error (KEEP: doctrine
+        // boundary is "ambiguous intent → refuse with next_action", not silence).
+        const detail = err instanceof Error ? err.message : (strictError?.message ?? String(err));
+        throw new Error(`cannot resolve mutation author: ${detail} `
+            + 'Pass a registered agent, set $BRAINCLAW_AGENT_NAME, '
+            + 'or register with `brainclaw register-agent <name>` before writing.', { cause: err });
+    }
+    const explicitSessionId = connectionSessionId?.trim() || explicitSessionIdFromEnv();
+    const hadSessionBefore = explicitSessionId
+        ? Boolean(loadSessionById(explicitSessionId, cwd))
+        : Boolean(loadCurrentSession(cwd));
+    let sessionAutoCreated;
+    try {
+        const opIdentity = buildOperationalIdentity(identity.agent_name, cwd, {
+            agentId: identity.agent_id,
+            sessionId: explicitSessionId,
+            persistImplicitSession: true,
+        });
+        if (!hadSessionBefore && opIdentity.session_id) {
+            sessionAutoCreated = opIdentity.session_id;
+            const session = loadSessionById(opIdentity.session_id, cwd);
+            if (session && !session.auto_created) {
+                saveCurrentSession({ ...session, auto_created: true }, cwd);
+            }
+        }
+    }
+    catch { /* best-effort — write can still proceed without a persisted session */ }
+    const autoRepair = (autoRegistered || sessionAutoCreated)
+        ? {
+            ...(autoRegistered ? { agent_auto_registered: true } : {}),
+            ...(sessionAutoCreated ? { session_auto_created: sessionAutoCreated } : {}),
+        }
+        : undefined;
+    return {
+        agent_name: identity.agent_name,
+        agent_id: identity.agent_id,
+        ...(autoRepair ? { auto_repair: autoRepair } : {}),
+    };
+}
+export function renderAutoRepairWarning(auto_repair, agent_name) {
+    const parts = [];
+    if (auto_repair.agent_auto_registered) {
+        parts.push(`agent '${agent_name}' auto-registered (first use). Run \`brainclaw register-agent ${agent_name}\` to set capabilities and trust level.`);
+    }
+    if (auto_repair.session_auto_created) {
+        parts.push(`session ${auto_repair.session_auto_created} auto-created for this write.`);
+    }
+    return `⚠️ auto-repair: ${parts.join(' ')}`;
+}
+export function scopeMetadataForTarget(args, targetCwd, effectiveScope) {
+    const hasExplicitProject = typeof args.project === 'string' && args.project.trim().length > 0;
+    return {
+        resolved_project: projectInfoForCwd(targetCwd),
+        active_source: hasExplicitProject ? 'explicit' : effectiveScope.active_source,
+    };
+}
+export function scanMcpWriteText(text, cwd) {
+    if (!text)
+        return { warnings: [] };
+    let config;
+    try {
+        config = loadConfig(cwd);
+    }
+    catch {
+        return { warnings: [] }; // no store/config to scan against — nothing to enforce
+    }
+    const found = scanText(text, config);
+    if (found.length === 0)
+        return { warnings: [] };
+    const warnings = found.map((w) => w.message);
+    if (found.some((w) => w.level === 'block')) {
+        return {
+            warnings,
+            blockResponse: toolResponse({
+                content: [{
+                        type: 'text',
+                        text: 'Blocked: strict redaction is enabled and the text contains sensitive content. Nothing was written.\n'
+                            + warnings.map((m) => `⚠ ${m}`).join('\n'),
+                    }],
+                structuredContent: { error: 'security_block', blocked_by: 'strict_redaction', security_warnings: warnings },
+            }, true),
+        };
+    }
+    return { warnings };
+}
+/**
+ * Append warn-level security warnings to a successful write response so the MCP
+ * caller sees them (parity with the CLI's printed warnings). No-op when there
+ * are no warnings, so responses for clean text stay byte-identical.
+ */
+export function appendSecurityWarnings(response, warnings) {
+    if (warnings.length === 0)
+        return response;
+    return {
+        ...response,
+        content: [...response.content, { type: 'text', text: warnings.map((m) => `⚠ security: ${m}`).join('\n') }],
+        structuredContent: { ...(response.structuredContent ?? {}), security_warnings: warnings },
+    };
+}
+//# sourceMappingURL=mcp-write-support.js.map