instar 0.28.82 → 0.28.84

package/dist/server/routes.js

@@ -78,6 +78,7 @@ import { ProcessIntegrity } from '../core/ProcessIntegrity.js';
 import { getOutboundQueueStatus, cleanupDeliveredOutbound, buildAgentList } from '../messaging/GitSyncTransport.js';
 import { verifyAgentToken, getAgentToken } from '../messaging/AgentTokenManager.js';
 import { createThreadlineRoutes } from '../threadline/ThreadlineEndpoints.js';
+import { ThreadlineNicknames } from '../threadline/ThreadlineNicknames.js';
 import { ScopeCoherenceTracker } from '../core/ScopeCoherenceTracker.js';
 import { isJunkPayload } from '../core/junk-payload.js';
 import { detectJargon } from '../core/JargonDetector.js';
@@ -2020,6 +2021,114 @@ export function createRoutes(ctx) {
             res.status(500).json({ error: err instanceof Error ? err.message : 'Context generation failed' });
         }
     });
+    // ── WikiClaim Phase 4 — Inverse-traceability HTTP endpoints ───────
+    //
+    // Per docs/specs/OPENCLAW-IMPORT-WIKICLAIM-EVIDENCE-SPEC.md § Phase 4
+    // (line 343) and § Inverse traceability (line 291).
+    //
+    // Both routes are thin pass-throughs to SemanticMemory's already-filtered
+    // typed methods (`getEvidence` / `findCitations`). Privacy enforcement
+    // lives ONE place — the storage layer's read-time filter (Phase 1) plus
+    // the EvidenceRenderer helper (Phase 5). These routes do not re-implement
+    // the filter; they invoke the methods and serialize the result.
+    //
+    // viewerScope derivation: the single bearer-token auth model has one
+    // principal (the agent itself), which sees its own data at `private`
+    // scope by default. Callers can request a NARROWED view via the
+    // `?viewerScope=shared-project|shared-topic|private` query param —
+    // useful for "what would a topic-peer see?" preview rendering in the
+    // dashboard. Widening above the auth principal is a no-op (the cap is
+    // `private`). Per spec § Storage and Privacy line 315 — the renderer is
+    // the privacy boundary; this route is a read endpoint with no
+    // judgment surface.
+    const VALID_EVIDENCE_KINDS = new Set([
+        'feedback', 'commit', 'session', 'document', 'message',
+        'job-run', 'ledger-entry', 'pattern-entity', 'external-url',
+        'supersedes-evidence',
+    ]);
+    const VALID_VIEWER_SCOPES = new Set(['shared-project', 'shared-topic', 'private']);
+    function resolveViewerScope(raw) {
+        if (typeof raw === 'string' && VALID_VIEWER_SCOPES.has(raw)) {
+            return raw;
+        }
+        // Default: agent has full visibility into its own DB.
+        return 'private';
+    }
+    // GET /memory/evidence/by-entity/:id
+    // Returns the entity's evidence array, viewer-scope filtered.
+    router.get('/memory/evidence/by-entity/:id', (req, res) => {
+        if (!ctx.semanticMemory) {
+            res.status(503).json({ error: 'Semantic memory not enabled' });
+            return;
+        }
+        try {
+            const entityId = req.params.id;
+            if (!entityId || typeof entityId !== 'string') {
+                res.status(400).json({ error: 'Missing entity id' });
+                return;
+            }
+            const viewerScope = resolveViewerScope(req.query.viewerScope);
+            // Existence + entity-level visibility check goes through the eager
+            // helper, which returns null when the entity is hidden (or missing)
+            // at the requested viewer scope. We deliberately collapse "entity
+            // exists but entity-scope wider than viewer" and "entity does not
+            // exist" into the same 404 — the spec's inverse-query non-leak rule
+            // (§ Storage and Privacy line 316) extends to direct fetch: a viewer
+            // at a narrower scope must not be able to probe entity existence by
+            // diffing 404 vs 200-empty.
+            const eager = ctx.semanticMemory.getEntityWithEvidence(entityId, viewerScope);
+            if (!eager) {
+                res.status(404).json({ error: 'Entity not found' });
+                return;
+            }
+            res.json({
+                entityId,
+                viewerScope,
+                evidence: eager.evidence,
+            });
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : 'Evidence lookup failed',
+            });
+        }
+    });
+    // GET /memory/entities/by-evidence?kind=feedback&sourceId=fb_123
+    // Returns entities citing (kind, sourceId), viewer-scope filtered.
+    router.get('/memory/entities/by-evidence', (req, res) => {
+        if (!ctx.semanticMemory) {
+            res.status(503).json({ error: 'Semantic memory not enabled' });
+            return;
+        }
+        try {
+            const kindRaw = req.query.kind;
+            const sourceIdRaw = req.query.sourceId;
+            const kind = typeof kindRaw === 'string' ? kindRaw : '';
+            const sourceId = typeof sourceIdRaw === 'string' ? sourceIdRaw : '';
+            if (!kind || !sourceId) {
+                res.status(400).json({ error: 'Missing required query params: kind, sourceId' });
+                return;
+            }
+            if (!VALID_EVIDENCE_KINDS.has(kind)) {
+                res.status(400).json({ error: `Invalid evidence kind: ${kind}` });
+                return;
+            }
+            const viewerScope = resolveViewerScope(req.query.viewerScope);
+            const entities = ctx.semanticMemory.findCitations({ kind: kind, sourceId }, viewerScope);
+            res.json({
+                kind,
+                sourceId,
+                viewerScope,
+                entities,
+                totalResults: entities.length,
+            });
+        }
+        catch (err) {
+            res.status(500).json({
+                error: err instanceof Error ? err.message : 'Citation lookup failed',
+            });
+        }
+    });
     // ── MEMORY.md Export (Phase 6) ─────────────────────────────────
     router.post('/semantic/export-memory', async (req, res) => {
         if (!ctx.semanticMemory) {
@@ -9150,6 +9259,23 @@ export function createRoutes(ctx) {
                         }
                     }
                 }
+                // ThreadlineFlowBridge: resume any TaskFlow flow waiting on a
+                // cross-agent-callback whose correlationId matches this inbound. The
+                // bridge runs after relay-accept (auth has passed), inspects only the
+                // envelope, and never alters the HTTP response — failures or misses
+                // are logged but not surfaced.
+                if (ctx.threadlineFlowBridge) {
+                    try {
+                        const bridgeResult = await ctx.threadlineFlowBridge.consumeInbound(envelope);
+                        if (bridgeResult.resumed) {
+                            console.log(`[relay-agent] ThreadlineFlowBridge resumed ${bridgeResult.flowIds.length} flow(s): ${bridgeResult.flowIds.join(', ')}`);
+                        }
+                    }
+                    catch (err) {
+                        if (err instanceof Error)
+                            console.error('[routes] ThreadlineFlowBridge error:', err.message);
+                    }
+                }
                 // If we have a ThreadlineRouter, route the message through it for
                 // session resume/spawn. We AWAIT the result so callers learn the real
                 // outcome (spawned / resumed / injected / handled:false). The message
@@ -9750,6 +9876,96 @@ export function createRoutes(ctx) {
             res.status(413).json({ success: false, error: 'Message too large (64KB limit)' });
             return;
         }
+        // Nickname-first resolution. User-curated names in nicknames.json are the
+        // highest-authority mapping (signal-vs-authority: relay discovery is signal,
+        // user nickname is authority). If "Dawn" maps to fingerprint X here, we
+        // route to X regardless of what the relay's discovery cache says about
+        // some other agent that also calls itself "Dawn". Skip when caller used
+        // a "name:fpPrefix" qualifier (they're explicitly disambiguating) or
+        // when the input already looks like a fingerprint.
+        let nicknameResolvedFp = null;
+        const looksLikeFingerprint = /^[0-9a-f]{16,64}$/i.test(targetAgent);
+        // Parse "name:fpPrefix" once so both branches below can reuse it.
+        const fpPrefixParse = (() => {
+            const ci = targetAgent.lastIndexOf(':');
+            if (ci <= 0 || ci >= targetAgent.length - 1)
+                return null;
+            const suffix = targetAgent.substring(ci + 1);
+            if (!/^[0-9a-f]{4,32}$/i.test(suffix))
+                return null;
+            return { name: targetAgent.substring(0, ci), fpPrefix: suffix.toLowerCase() };
+        })();
+        const usesFpPrefixSyntax = fpPrefixParse !== null;
+        if (!looksLikeFingerprint) {
+            try {
+                const nicknameStore = new ThreadlineNicknames({ stateDir: ctx.config.stateDir });
+                // For "name:fpPrefix" inputs, look up the bare name in the nickname
+                // store and filter the candidates by the prefix. This lets the user
+                // disambiguate ambiguous nickname entries with the same syntax that
+                // works for known-agents.json — the spec promises this remedy.
+                // Without this, "Dawn:abcd" would skip nickname lookup entirely and
+                // the documented disambiguation path would be a dead end.
+                const lookupName = fpPrefixParse ? fpPrefixParse.name : targetAgent;
+                const lookup = nicknameStore.resolveByName(lookupName);
+                if (lookup && 'ambiguous' in lookup) {
+                    if (fpPrefixParse) {
+                        const matched = lookup.candidates.filter(c => c.fingerprint.toLowerCase().startsWith(fpPrefixParse.fpPrefix));
+                        if (matched.length === 1) {
+                            nicknameResolvedFp = matched[0].fingerprint;
+                        }
+                        else if (matched.length === 0) {
+                            const hints = lookup.candidates
+                                .map(c => `${c.entry.nickname}:${c.fingerprint.substring(0, 8)}`)
+                                .join(', ');
+                            res.status(409).json({
+                                success: false,
+                                error: `Nickname "${fpPrefixParse.name}" has no candidate matching prefix "${fpPrefixParse.fpPrefix}". Candidates: ${hints}.`,
+                            });
+                            return;
+                        }
+                        else {
+                            const hints = matched
+                                .map(c => `${c.entry.nickname}:${c.fingerprint.substring(0, 8)}`)
+                                .join(', ');
+                            res.status(409).json({
+                                success: false,
+                                error: `Prefix "${fpPrefixParse.fpPrefix}" still ambiguous among nickname "${fpPrefixParse.name}" candidates: ${hints}. Use a longer prefix.`,
+                            });
+                            return;
+                        }
+                    }
+                    else {
+                        const hints = lookup.candidates
+                            .map(c => `${c.entry.nickname}:${c.fingerprint.substring(0, 8)} (${c.fingerprint})`)
+                            .join(', ');
+                        res.status(409).json({
+                            success: false,
+                            error: `Ambiguous nickname "${targetAgent}" — multiple fingerprints share this name in nicknames.json: ${hints}. Send by fingerprint or use "name:fpPrefix" syntax.`,
+                        });
+                        return;
+                    }
+                }
+                else if (lookup) {
+                    // Single-candidate match. If caller also passed a fpPrefix, sanity-
+                    // check that it agrees with the curated mapping; on disagreement,
+                    // honor the caller's explicit prefix (they may be telling us the
+                    // nickname is stale) and skip nickname authority for this send.
+                    if (fpPrefixParse && !lookup.fingerprint.toLowerCase().startsWith(fpPrefixParse.fpPrefix)) {
+                        console.warn(`[relay-send] Nickname/prefix disagreement for "${fpPrefixParse.name}": ` +
+                            `nickname maps to ${lookup.fingerprint.substring(0, 8)}…, ` +
+                            `caller prefix is "${fpPrefixParse.fpPrefix}". Honoring caller prefix.`);
+                    }
+                    else {
+                        nicknameResolvedFp = lookup.fingerprint;
+                    }
+                }
+            }
+            catch (err) {
+                // Nickname store read failed — fall through to existing resolution.
+                // Don't block sends on a corrupt nicknames file.
+                console.warn(`[relay-send] Nickname store read failed (non-fatal): ${err instanceof Error ? err.message : err}`);
+            }
+        }
         const msgId = `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
         // Mint a stable UUID threadId when caller didn't provide one so
         // first-contact messages aren't dropped on the recipient side. Both
@@ -9775,7 +9991,14 @@ export function createRoutes(ctx) {
                         targetFpPrefix = suffix.toLowerCase();
                     }
                 }
-                const nameMatches = agents.filter(a => a.name === targetName || a.name?.toLowerCase() === targetName?.toLowerCase());
+                // If a nickname resolved upstream, prefer fingerprint match over
+                // name match — the user-curated mapping is authoritative.
+                const nameMatches = nicknameResolvedFp
+                    ? agents.filter(a => {
+                        const fp = (a.fingerprint || a.publicKey?.substring(0, 32) || '').toLowerCase();
+                        return fp === nicknameResolvedFp.toLowerCase();
+                    })
+                    : agents.filter(a => a.name === targetName || a.name?.toLowerCase() === targetName?.toLowerCase());
                 // PR-3: Fingerprint-based disambiguation. If multiple known agents
                 // share a name, require a `name:fpPrefix` qualifier to pick one.
                 // Previously this silently fell through to the relay, which then
@@ -9972,8 +10195,31 @@ export function createRoutes(ctx) {
             return;
         }
         try {
-            // Resolve name → fingerprint if targetAgent isn't already a fingerprint
-            const resolvedId = await relayClient.resolveAgent(targetAgent);
+            // Resolve name → fingerprint. Nickname store wins over relay discovery
+            // when the user has explicitly curated a mapping (set above). Falling
+            // back to relay discovery only when no nickname matched. If the relay
+            // happens to also know this name but maps it to a different fingerprint,
+            // we silently override with the nickname mapping — the user's choice is
+            // authority. Logged so the conflict is visible in operator logs.
+            let resolvedId;
+            if (nicknameResolvedFp) {
+                resolvedId = nicknameResolvedFp;
+                try {
+                    const discoveryFp = await relayClient.resolveAgent(targetAgent);
+                    if (discoveryFp && discoveryFp.toLowerCase() !== nicknameResolvedFp.toLowerCase()) {
+                        console.warn(`[relay-send] Nickname/discovery mismatch for "${targetAgent}": ` +
+                            `nickname maps to ${nicknameResolvedFp.substring(0, 8)}…, ` +
+                            `relay discovery returned ${discoveryFp.substring(0, 8)}…. ` +
+                            `Honoring user-curated nickname.`);
+                    }
+                }
+                catch {
+                    // Discovery probe is best-effort for the conflict warning only.
+                }
+            }
+            else {
+                resolvedId = await relayClient.resolveAgent(targetAgent);
+            }
             if (!resolvedId) {
                 res.status(404).json({
                     success: false,
@@ -11614,6 +11860,250 @@ export function createRoutes(ctx) {
             idleExpiresAt: result.result.idleExpiresAt,
         });
     });
+    // ─── TaskFlow registry (OpenClaw import — Phase 1) ──────────────────
+    // Admin Bearer-token auth via global authMiddleware. The HTTP API exists for
+    // debugging and out-of-process tooling; production controllers run
+    // in-process inside the server and call the registry directly.
+    // See docs/specs/OPENCLAW-IMPORT-TASKFLOW-SPEC.md.
+    {
+        const taskFlowError = (res, err) => {
+            const e = err;
+            if (e?.name !== 'TaskFlowError') {
+                res.status(500).json({ error: 'internal_error', message: e?.message });
+                return;
+            }
+            const status = {
+                not_found: 404,
+                revision_conflict: 409,
+                already_terminal: 410,
+                invalid_transition: 422,
+                invalid_argument: 422,
+                unauthorized_controller: 422,
+                already_consumed: 422,
+                wait_collision: 422,
+                quota_exceeded: 429,
+            }[e.code ?? ''] ?? 500;
+            // Phase 5: rate-limit responses surface Retry-After header for HTTP-compliant
+            // clients in addition to the in-body retryAfterMs hint. RFC 7231 § 7.1.3
+            // specifies seconds; we round UP so a sub-second retry maps to 1.
+            if (status === 429 && typeof e.detail?.retryAfterMs === 'number') {
+                const retryAfterMs = e.detail.retryAfterMs;
+                const seconds = Math.max(1, Math.ceil(retryAfterMs / 1000));
+                try {
+                    res.setHeader('Retry-After', String(seconds));
+                }
+                catch { /* swallow */ }
+            }
+            res.status(status).json({ error: e.code, ...(e.detail ?? {}), message: e.message });
+        };
+        router.post('/flows', async (req, res) => {
+            if (!ctx.taskFlowRegistry) {
+                res.status(503).json({ error: 'taskflow_not_enabled' });
+                return;
+            }
+            try {
+                const out = await ctx.taskFlowRegistry.createFlow(req.body ?? {});
+                res.status(out.created ? 201 : 200).json(out.flow);
+            }
+            catch (err) {
+                if (err instanceof Error)
+                    taskFlowError(res, err);
+                else
+                    res.status(500).json({ error: 'internal_error' });
+            }
+        });
+        router.get('/flows/:flowId', (req, res) => {
+            if (!ctx.taskFlowRegistry) {
+                res.status(503).json({ error: 'taskflow_not_enabled' });
+                return;
+            }
+            const flow = ctx.taskFlowRegistry.getFlow(req.params.flowId);
+            if (!flow) {
+                res.status(404).json({ error: 'not_found', flowId: req.params.flowId });
+                return;
+            }
+            // The owning controller may identify itself via header to receive the
+            // unredacted record. Otherwise we return the redacted shape (no
+            // stateJson, waitJson reduced to {kind}).
+            const callerControllerId = req.header('x-taskflow-controller-id');
+            if (callerControllerId && callerControllerId === flow.controllerId) {
+                res.json(flow);
+                return;
+            }
+            res.json(ctx.taskFlowRegistry.getRedactedFlow(req.params.flowId));
+        });
+        router.get('/flows/waiting', (req, res) => {
+            if (!ctx.taskFlowRegistry) {
+                res.status(503).json({ error: 'taskflow_not_enabled' });
+                return;
+            }
+            const channel = typeof req.query.channel === 'string' ? req.query.channel : undefined;
+            const threadId = typeof req.query.threadId === 'string' ? req.query.threadId : undefined;
+            const peer = typeof req.query.peer === 'string' ? req.query.peer : undefined;
+            const correlationId = typeof req.query.correlationId === 'string' ? req.query.correlationId : undefined;
+            const waitKind = typeof req.query.waitKind === 'string' ? req.query.waitKind : undefined;
+            if (channel && threadId && peer) {
+                res.json({
+                    matches: ctx.taskFlowRegistry.findWaitingByReply({ channel, threadId, peer }),
+                });
+                return;
+            }
+            if (correlationId && (waitKind === 'external-call' || waitKind === 'cross-agent-callback')) {
+                res.json({
+                    matches: ctx.taskFlowRegistry.findWaitingByCorrelation({ waitKind, correlationId }),
+                });
+                return;
+            }
+            res.status(400).json({ error: 'invalid_query', message: 'specify (channel,threadId,peer) or (correlationId,waitKind)' });
+        });
+        const occMutationHandler = (op) => async (req, res) => {
+            if (!ctx.taskFlowRegistry) {
+                res.status(503).json({ error: 'taskflow_not_enabled' });
+                return;
+            }
+            const body = (req.body ?? {});
+            const flowId = req.params.flowId;
+            const expectedRevision = Number(body.expectedRevision);
+            if (!Number.isFinite(expectedRevision)) {
+                res.status(422).json({ error: 'invalid_argument', field: 'expectedRevision' });
+                return;
+            }
+            const principal = body.principal;
+            if (!principal || typeof principal !== 'object' || !('scope' in principal)) {
+                res.status(422).json({ error: 'invalid_argument', field: 'principal' });
+                return;
+            }
+            try {
+                let result;
+                switch (op) {
+                    case 'startStep':
+                        result = await ctx.taskFlowRegistry.startStep({
+                            flowId,
+                            expectedRevision,
+                            principal: principal,
+                            currentStep: String(body.currentStep ?? ''),
+                        });
+                        break;
+                    case 'setFlowWaiting':
+                        result = await ctx.taskFlowRegistry.setFlowWaiting({
+                            flowId,
+                            expectedRevision,
+                            principal: principal,
+                            waitJson: body.waitJson,
+                            currentStep: body.currentStep,
+                            statePatch: body.statePatch,
+                        });
+                        break;
+                    case 'resumeFlow':
+                        result = await ctx.taskFlowRegistry.resumeFlow({
+                            flowId,
+                            expectedRevision,
+                            principal: principal,
+                            waitInstanceId: String(body.waitInstanceId ?? ''),
+                            currentStep: body.currentStep,
+                            statePatch: body.statePatch,
+                        });
+                        break;
+                    case 'finishFlow':
+                        result = await ctx.taskFlowRegistry.finishFlow({
+                            flowId,
+                            expectedRevision,
+                            principal: principal,
+                            result: body.result,
+                        });
+                        break;
+                    case 'failFlow':
+                        result = await ctx.taskFlowRegistry.failFlow({
+                            flowId,
+                            expectedRevision,
+                            principal: principal,
+                            failureReason: String(body.failureReason ?? ''),
+                        });
+                        break;
+                    case 'cancelFlow':
+                        result = await ctx.taskFlowRegistry.cancelFlow({
+                            flowId,
+                            expectedRevision,
+                            principal: principal,
+                        });
+                        break;
+                    case 'markLost':
+                        result = await ctx.taskFlowRegistry.markLost({
+                            flowId,
+                            expectedRevision,
+                            ledgerEntryId: String(body.ledgerEntryId ?? ''),
+                            reason: body.reason === 'stranded' ? 'stranded' : 'lost',
+                        });
+                        break;
+                }
+                res.json(result);
+            }
+            catch (err) {
+                if (err instanceof Error)
+                    taskFlowError(res, err);
+                else
+                    res.status(500).json({ error: 'internal_error' });
+            }
+        };
+        router.post('/flows/:flowId/start-step', occMutationHandler('startStep'));
+        router.post('/flows/:flowId/wait', occMutationHandler('setFlowWaiting'));
+        router.post('/flows/:flowId/resume', occMutationHandler('resumeFlow'));
+        router.post('/flows/:flowId/finish', occMutationHandler('finishFlow'));
+        router.post('/flows/:flowId/fail', occMutationHandler('failFlow'));
+        router.post('/flows/:flowId/cancel-flow', occMutationHandler('cancelFlow'));
+        router.post('/flows/:flowId/mark-lost', occMutationHandler('markLost'));
+        router.post('/flows/:flowId/cancel-request', async (req, res) => {
+            if (!ctx.taskFlowRegistry) {
+                res.status(503).json({ error: 'taskflow_not_enabled' });
+                return;
+            }
+            const body = (req.body ?? {});
+            const expectedRevision = Number(body.expectedRevision);
+            if (!Number.isFinite(expectedRevision)) {
+                res.status(422).json({ error: 'invalid_argument', field: 'expectedRevision' });
+                return;
+            }
+            try {
+                const result = await ctx.taskFlowRegistry.requestFlowCancel({
+                    flowId: req.params.flowId,
+                    expectedRevision,
+                    requesterOrigin: body.requesterOrigin,
+                });
+                res.json(result);
+            }
+            catch (err) {
+                if (err instanceof Error)
+                    taskFlowError(res, err);
+                else
+                    res.status(500).json({ error: 'internal_error' });
+            }
+        });
+        router.post('/flows/:flowId/ping', async (req, res) => {
+            if (!ctx.taskFlowRegistry) {
+                res.status(503).json({ error: 'taskflow_not_enabled' });
+                return;
+            }
+            const body = (req.body ?? {});
+            const principal = body.principal;
+            if (!principal || principal.scope !== 'controller') {
+                res.status(422).json({ error: 'invalid_argument', field: 'principal' });
+                return;
+            }
+            try {
+                const flow = await ctx.taskFlowRegistry.pingFlow({
+                    flowId: req.params.flowId,
+                    principal,
+                });
+                res.json(flow);
+            }
+            catch (err) {
+                if (err instanceof Error)
+                    taskFlowError(res, err);
+                else
+                    res.status(500).json({ error: 'internal_error' });
+            }
+        });
+    }
     return router;
 }
 export function formatUptime(ms) {