instar 0.28.83 → 0.28.85

package/dist/server/routes.js

@@ -2021,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) {
@@ -4728,7 +4836,7 @@ export function createRoutes(ctx) {
         }
         res.json(initiative);
     });
-    router.post('/initiatives', (req, res) => {
+    router.post('/initiatives', async (req, res) => {
         if (!ctx.initiativeTracker) {
             res.status(503).json({ error: 'Initiative tracker not configured' });
             return;
@@ -4751,7 +4859,7 @@ export function createRoutes(ctx) {
             return;
         }
         try {
-            const created = ctx.initiativeTracker.create({
+            const created = await ctx.initiativeTracker.create({
                 id, title, description, phases, links, nextCheckAt,
                 needsUser, needsUserReason, blockers,
             });
@@ -4761,7 +4869,7 @@ export function createRoutes(ctx) {
             res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
         }
     });
-    router.patch('/initiatives/:id', (req, res) => {
+    router.patch('/initiatives/:id', async (req, res) => {
         if (!ctx.initiativeTracker) {
             res.status(503).json({ error: 'Initiative tracker not configured' });
             return;
@@ -4771,7 +4879,7 @@ export function createRoutes(ctx) {
             return;
         }
         try {
-            const updated = ctx.initiativeTracker.update(req.params.id, req.body ?? {});
+            const updated = await ctx.initiativeTracker.update(req.params.id, req.body ?? {});
             res.json(updated);
         }
         catch (err) {
@@ -4780,7 +4888,7 @@ export function createRoutes(ctx) {
             res.status(status).json({ error: msg });
         }
     });
-    router.post('/initiatives/:id/phase/:phaseId', (req, res) => {
+    router.post('/initiatives/:id/phase/:phaseId', async (req, res) => {
         if (!ctx.initiativeTracker) {
             res.status(503).json({ error: 'Initiative tracker not configured' });
             return;
@@ -4791,7 +4899,7 @@ export function createRoutes(ctx) {
             return;
         }
         try {
-            const updated = ctx.initiativeTracker.setPhaseStatus(req.params.id, req.params.phaseId, status);
+            const updated = await ctx.initiativeTracker.setPhaseStatus(req.params.id, req.params.phaseId, status);
             res.json(updated);
         }
         catch (err) {
@@ -4799,12 +4907,12 @@ export function createRoutes(ctx) {
             res.status(msg.includes('not found') ? 404 : 400).json({ error: msg });
         }
     });
-    router.delete('/initiatives/:id', (req, res) => {
+    router.delete('/initiatives/:id', async (req, res) => {
         if (!ctx.initiativeTracker) {
             res.status(503).json({ error: 'Initiative tracker not configured' });
             return;
         }
-        const removed = ctx.initiativeTracker.remove(req.params.id);
+        const removed = await ctx.initiativeTracker.remove(req.params.id);
         if (!removed) {
             res.status(404).json({ error: 'initiative not found' });
             return;
@@ -6723,12 +6831,12 @@ export function createRoutes(ctx) {
         const applied = req.query.applied !== undefined ? req.query.applied === 'true' : undefined;
         res.json({ learnings: ctx.evolution.listLearnings({ category, applied }) });
     });
-    router.post('/evolution/learnings', (req, res) => {
+    router.post('/evolution/learnings', async (req, res) => {
         if (!ctx.evolution) {
             res.status(503).json({ error: 'Evolution system not configured' });
             return;
         }
-        const { title, category, description, source, tags, evolutionRelevance } = req.body;
+        const { title, category, description, source, tags, evolutionRelevance, context, documentFallback, evidence: explicitEvidence } = req.body;
         if (!title || typeof title !== 'string' || title.length > 500) {
             res.status(400).json({ error: '"title" must be a string under 500 characters' });
             return;
@@ -6737,6 +6845,43 @@ export function createRoutes(ctx) {
             res.status(400).json({ error: '"description" is required' });
             return;
         }
+        // WikiClaim Phase 3 (spec § Producers line 268, § Migration Plan line 341):
+        // /learn must cite at least one evidence row. Either:
+        //   (a) caller passes `evidence: MemoryEvidence[]` directly (advanced),
+        //   (b) caller passes `context: string` and we auto-derive sessions/messages,
+        //   (c) caller passes `documentFallback: {sourceId, path}` for prompted-source.
+        // Combining (b)+(c) is allowed.
+        let derivedEvidence = [];
+        let externalReferences = [];
+        let pendingDocumentRef;
+        try {
+            if (Array.isArray(explicitEvidence) && explicitEvidence.length > 0) {
+                derivedEvidence = explicitEvidence;
+            }
+            else {
+                const { buildLearnEvidence, LearnEvidenceError } = await import('../core/LearnSkillBridge.js');
+                try {
+                    const built = buildLearnEvidence({
+                        context: typeof context === 'string' ? context : `${title}\n\n${description}`,
+                        documentFallback,
+                    });
+                    derivedEvidence = built.evidence;
+                    externalReferences = built.externalReferences;
+                    pendingDocumentRef = built.pendingDocumentRef;
+                }
+                catch (err) {
+                    if (err instanceof LearnEvidenceError) {
+                        res.status(400).json({ error: err.message });
+                        return;
+                    }
+                    throw err;
+                }
+            }
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : 'Failed to derive evidence' });
+            return;
+        }
         const learning = ctx.evolution.addLearning({
             title, category: category || 'general', description,
             source: source || { discoveredAt: new Date().toISOString() },
@@ -6753,7 +6898,18 @@ export function createRoutes(ctx) {
                 soulNudge = 'This learning may be identity-relevant. Consider updating soul.md or running /reflect.';
             }
         }
-        res.status(201).json({ ...learning, soulNudge });
+        // WikiClaim Phase 3: surface derived evidence + external references on
+        // the response so callers can confirm the bridge resolved their context.
+        // Spec § Producers line 228 — LearnSkill kinds are message|session;
+        // externalReferences carry feedback/commit refs that the caller routes
+        // through the appropriate downstream producer.
+        res.status(201).json({
+            ...learning,
+            soulNudge,
+            evidence: derivedEvidence,
+            externalReferences,
+            ...(pendingDocumentRef ? { pendingDocumentRef } : {}),
+        });
     });
     router.patch('/evolution/learnings/:id/apply', (req, res) => {
         if (!ctx.evolution) {
@@ -7408,14 +7564,46 @@ export function createRoutes(ctx) {
     router.post('/intent/journal', async (req, res) => {
         try {
             const { DecisionJournal } = await import('../core/DecisionJournal.js');
+            const { EvidencePolicyError } = await import('../memory/SemanticMemory.js');
             const journal = new DecisionJournal(ctx.config.stateDir);
-            const { sessionId, decision, ...rest } = req.body || {};
+            const { sessionId, decision, evidence, ...rest } = req.body || {};
             if (!sessionId || !decision) {
                 res.status(400).json({ error: 'sessionId and decision are required' });
                 return;
             }
-            const entry = journal.log({ sessionId, decision, ...rest });
-            res.status(201).json(entry);
+            // WikiClaim Phase 3 (spec § Producers line 258): every decision must
+            // cite at least one evidence row. The route accepts an explicit
+            // `evidence` array, OR — when omitted — synthesizes a minimum-viable
+            // `session` evidence row from the request's `sessionId` (the auth-
+            // context proxy available at this HTTP layer). Synthesis keeps the
+            // legacy POST shape working while still satisfying the policy gate;
+            // explicit evidence always overrides synthesis. Spec § Producers
+            // line 227: `session` is in the DecisionJournal allowlist. Spec
+            // § Storage and Privacy line 333: synthetic sourceIds are tolerated
+            // (consumers handle dangling refs).
+            let effectiveEvidence = Array.isArray(evidence) ? evidence : [];
+            if (effectiveEvidence.length === 0) {
+                effectiveEvidence = [{
+                        kind: 'session',
+                        sourceId: `session:${sessionId}`,
+                        weight: 0.5,
+                        confidence: 0.5,
+                        privacyTier: 'private',
+                        note: 'auto-synthesized from request session (no explicit evidence)',
+                        updatedAt: new Date().toISOString(),
+                    }];
+            }
+            try {
+                const entry = journal.log({ sessionId, decision, ...rest }, effectiveEvidence);
+                res.status(201).json(entry);
+            }
+            catch (err) {
+                if (err instanceof EvidencePolicyError) {
+                    res.status(400).json({ error: err instanceof Error ? err.message : String(err) });
+                    return;
+                }
+                throw err;
+            }
         }
         catch (err) {
             res.status(500).json({ error: err instanceof Error ? err.message : 'Failed to log decision' });
@@ -9151,6 +9339,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
@@ -10162,6 +10367,43 @@ export function createRoutes(ctx) {
             });
         }
     });
+    // ── Threadline Relay Discover ────────────────────────────────────────
+    // Proxies a discover query through the agent server's relay WebSocket so
+    // the MCP stdio subprocess can ask the relay for its live presence registry
+    // (the MCP subprocess doesn't have its own relay client — same arrangement
+    // as /threadline/relay-send above).
+    router.post('/threadline/relay-discover', async (req, res) => {
+        const relayClient = ctx.threadlineRelayClient;
+        if (!relayClient || relayClient.connectionState !== 'connected') {
+            res.status(503).json({
+                success: false,
+                error: 'Relay not connected',
+                connectionState: relayClient?.connectionState ?? 'absent',
+            });
+            return;
+        }
+        const filter = (req.body && typeof req.body === 'object') ? req.body.filter : undefined;
+        try {
+            const agents = await relayClient.discover(filter);
+            res.json({
+                success: true,
+                agents: agents.map(a => ({
+                    agentId: a.agentId,
+                    name: a.name,
+                    publicKey: Buffer.isBuffer(a.publicKey) ? a.publicKey.toString('hex') : a.publicKey,
+                    framework: a.framework,
+                    capabilities: a.capabilities,
+                    lastSeen: a.lastSeen,
+                })),
+            });
+        }
+        catch (err) {
+            res.status(500).json({
+                success: false,
+                error: err instanceof Error ? err.message : 'Discover failed',
+            });
+        }
+    });
     // ── Response Review Pipeline (Coherence Gate) ────────────────────────
     //
     // Evaluates agent responses before delivery. Implements PEL + Gate + Specialist
@@ -11735,6 +11977,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) {