@exaudeus/workrail 3.14.0 → 3.16.0

package/dist/mcp/handlers/v2-execution/start.js

@@ -6,15 +6,14 @@ exports.mintStartTokens = mintStartTokens;
 exports.executeStartWorkflow = executeStartWorkflow;
 const output_schemas_js_1 = require("../../output-schemas.js");
 const step_instance_key_js_1 = require("../../../v2/durable-core/schemas/execution-snapshot/step-instance-key.js");
-const workflow_js_1 = require("../../../types/workflow.js");
 const index_js_1 = require("../../../v2/durable-core/ids/index.js");
 const workflow_hash_ref_js_1 = require("../../../v2/durable-core/ids/workflow-hash-ref.js");
 const neverthrow_1 = require("neverthrow");
 const workflow_validation_pipeline_js_1 = require("../../../application/services/workflow-validation-pipeline.js");
 const hashing_js_1 = require("../../../v2/durable-core/canonical/hashing.js");
 const observation_builder_js_1 = require("../../../v2/durable-core/domain/observation-builder.js");
-const workflow_source_js_1 = require("../../../types/workflow-source.js");
 const workflow_definition_js_1 = require("../../../types/workflow-definition.js");
+const workflow_object_cache_js_1 = require("./workflow-object-cache.js");
 const prompt_renderer_js_1 = require("../../../v2/durable-core/domain/prompt-renderer.js");
 const v2_workspace_resolution_js_1 = require("../v2-workspace-resolution.js");
 const v2_token_ops_js_1 = require("../v2-token-ops.js");
@@ -73,13 +72,13 @@ function loadAndPinWorkflow(args) {
             return pinnedStore.get(workflowHash)
                 .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
                 .andThen((existingPinned) => {
-                if (!existingPinned) {
-                    return pinnedStore.put(workflowHash, enrichedCompiled)
-                        .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }));
+                if (existingPinned) {
+                    return (0, neverthrow_1.okAsync)(existingPinned);
                 }
-                return (0, neverthrow_1.okAsync)(undefined);
+                return pinnedStore.put(workflowHash, enrichedCompiled)
+                    .mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause }))
+                    .andThen(() => pinnedStore.get(workflowHash).mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause })));
             })
-                .andThen(() => pinnedStore.get(workflowHash).mapErr((cause) => ({ kind: 'pinned_workflow_store_failed', cause })))
                 .andThen((pinned) => {
                 if (!pinned || pinned.sourceKind !== 'v1_pinned' || !(0, workflow_definition_js_1.hasWorkflowDefinitionShape)(pinned.definition)) {
                     return (0, neverthrow_1.errAsync)({
@@ -87,7 +86,7 @@ function loadAndPinWorkflow(args) {
                         message: 'Failed to pin executable workflow snapshot (missing or invalid pinned workflow).',
                     });
                 }
-                const pinnedWorkflow = (0, workflow_js_1.createWorkflow)(pinned.definition, (0, workflow_source_js_1.createBundledSource)());
+                const pinnedWorkflow = (0, workflow_object_cache_js_1.getCachedWorkflow)(workflowHash, pinned.definition);
                 const resolution = (0, start_construction_js_1.resolveFirstStep)(workflow, pinned);
                 if (resolution.isErr()) {
                     const error = resolution.error.reason === 'no_steps'
@@ -108,7 +107,7 @@ function loadAndPinWorkflow(args) {
     });
 }
 function buildInitialEvents(args) {
-    const { sessionId, runId, nodeId, workflowId, workflowHash, workflowSourceKind, workflowSourceRef, snapshotRef, observations, idFactory, } = args;
+    const { sessionId, runId, nodeId, workflowId, workflowHash, workflowSourceKind, workflowSourceRef, snapshotRef, observations, idFactory, goal, } = args;
     const evtSessionCreated = idFactory.mintEventId();
     const evtRunStarted = idFactory.mintEventId();
     const evtNodeCreated = idFactory.mintEventId();
@@ -177,6 +176,24 @@ function buildInitialEvents(args) {
         },
     ];
     const mutableEvents = [...baseEvents];
+    {
+        const contextEventId = idFactory.mintEventId();
+        const contextId = idFactory.mintEventId();
+        mutableEvents.push({
+            v: 1,
+            eventId: contextEventId,
+            eventIndex: mutableEvents.length,
+            sessionId,
+            kind: constants_js_1.EVENT_KIND.CONTEXT_SET,
+            dedupeKey: `context_set:${sessionId}:${String(runId)}:initial`,
+            scope: { runId: String(runId) },
+            data: {
+                contextId,
+                context: { goal },
+                source: 'initial',
+            },
+        });
+    }
     for (const obs of observations) {
         const obsEventId = idFactory.mintEventId();
         mutableEvents.push({
@@ -289,11 +306,13 @@ function executeStartWorkflow(input, ctx) {
                     snapshotRef,
                     observations,
                     idFactory,
+                    goal: input.goal,
                 });
+                const emptyTruth = { manifest: [], events: [] };
                 return gate.withHealthySessionLock(sessionId, (lock) => sessionStore.append(lock, {
                     events,
                     snapshotPins: [{ snapshotRef, eventIndex: 2, createdByEventId: events[2].eventId }],
-                }))
+                }, emptyTruth))
                     .mapErr((cause) => ({ kind: 'session_append_failed', cause }))
                     .map(() => ({ workflow, firstStep, workflowHash, pinnedWorkflow, resolvedReferences, sessionId, runId, nodeId }));
             });
@@ -342,7 +361,7 @@ function executeStartWorkflow(input, ctx) {
                 meta,
                 references: resolvedReferences,
             });
-            const parsed = output_schemas_js_1.V2StartWorkflowOutputSchema.parse({
+            const parsed = {
                 continueToken: tokens.continueToken,
                 checkpointToken: tokens.checkpointToken,
                 isComplete: false,
@@ -351,7 +370,7 @@ function executeStartWorkflow(input, ctx) {
                 nextIntent,
                 nextCall: (0, index_js_2.buildNextCall)({ continueToken: tokens.continueToken, isComplete: false, pending }),
                 ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
-            });
+            };
             return (0, neverthrow_1.okAsync)({ response: parsed, contentEnvelope });
         });
     }));

package/dist/mcp/handlers/v2-execution/workflow-object-cache.d.ts

@@ -0,0 +1,5 @@
+import type { WorkflowDefinition } from '../../../types/workflow-definition.js';
+import type { Workflow } from '../../../types/workflow.js';
+import type { WorkflowHash } from '../../../v2/durable-core/ids/index.js';
+export declare function getCachedWorkflow(workflowHash: WorkflowHash, definition: WorkflowDefinition): Workflow;
+export declare function clearWorkflowObjectCacheForTesting(): void;

package/dist/mcp/handlers/v2-execution/workflow-object-cache.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCachedWorkflow = getCachedWorkflow;
+exports.clearWorkflowObjectCacheForTesting = clearWorkflowObjectCacheForTesting;
+const workflow_js_1 = require("../../../types/workflow.js");
+const workflow_source_js_1 = require("../../../types/workflow-source.js");
+const _cache = new Map();
+function getCachedWorkflow(workflowHash, definition) {
+    const key = String(workflowHash);
+    const existing = _cache.get(key);
+    if (existing !== undefined)
+        return existing;
+    const wf = (0, workflow_js_1.createWorkflow)(definition, (0, workflow_source_js_1.createBundledSource)());
+    _cache.set(key, wf);
+    return wf;
+}
+function clearWorkflowObjectCacheForTesting() {
+    _cache.clear();
+}

package/dist/mcp/handlers/v2-execution-helpers.d.ts

@@ -120,4 +120,5 @@ export declare function derivePreferencesOrDefault(args: {
     readonly truth: LoadedSessionTruthV2;
     readonly runId: RunId;
     readonly nodeId: NodeId;
+    readonly precomputedIndex?: import('../../v2/durable-core/session-index.js').SessionIndex;
 }): PreferencesV2;

package/dist/mcp/handlers/v2-execution-helpers.js

@@ -266,20 +266,36 @@ function mapSessionOrGateErrorToToolError(e) {
 }
 const constants_js_1 = require("../../v2/durable-core/constants.js");
 const preferences_js_1 = require("../../v2/projections/preferences.js");
+const sorted_event_log_js_1 = require("../../v2/durable-core/sorted-event-log.js");
 exports.defaultPreferences = {
     autonomy: 'guided',
     riskPolicy: 'conservative'
 };
 function derivePreferencesOrDefault(args) {
+    let sortedEventsForPrefs;
     const parentByNodeId = {};
-    for (const e of args.truth.events) {
-        if (e.kind !== constants_js_1.EVENT_KIND.NODE_CREATED)
-            continue;
-        if (e.scope?.runId !== String(args.runId))
-            continue;
-        parentByNodeId[String(e.scope.nodeId)] = e.data.parentNodeId;
+    if (args.precomputedIndex) {
+        sortedEventsForPrefs = args.precomputedIndex.sortedEvents;
+        for (const [nodeId, evt] of args.precomputedIndex.nodeCreatedByNodeId) {
+            if (evt.scope.runId === String(args.runId)) {
+                parentByNodeId[nodeId] = evt.data.parentNodeId ?? null;
+            }
+        }
+    }
+    else {
+        for (const e of args.truth.events) {
+            if (e.kind !== constants_js_1.EVENT_KIND.NODE_CREATED)
+                continue;
+            if (e.scope?.runId !== String(args.runId))
+                continue;
+            parentByNodeId[String(e.scope.nodeId)] = e.data.parentNodeId;
+        }
+        const sortedEventsRes = (0, sorted_event_log_js_1.asSortedEventLog)(args.truth.events);
+        if (sortedEventsRes.isErr())
+            return exports.defaultPreferences;
+        sortedEventsForPrefs = sortedEventsRes.value;
     }
-    const prefs = (0, preferences_js_1.projectPreferencesV2)(args.truth.events, parentByNodeId);
+    const prefs = (0, preferences_js_1.projectPreferencesV2)(sortedEventsForPrefs, parentByNodeId);
     if (prefs.isErr())
         return exports.defaultPreferences;
     const p = prefs.value.byNodeId[String(args.nodeId)]?.effective;

package/dist/mcp/handlers/v2-resume.d.ts

@@ -1,7 +1,7 @@
 import type { z } from 'zod';
 import type { V2ResumeSessionInput } from '../v2/tools.js';
 import type { ToolContext, ToolResult } from '../types.js';
-import { V2ResumeSessionOutputSchema } from '../output-schemas.js';
+import type { V2ResumeSessionOutputSchema } from '../output-schemas.js';
 type ResumeInput = z.infer<typeof V2ResumeSessionInput>;
 type ResumeOutput = z.infer<typeof V2ResumeSessionOutputSchema>;
 export declare function handleV2ResumeSession(input: ResumeInput, ctx: ToolContext): Promise<ToolResult<ResumeOutput>>;

package/dist/mcp/handlers/v2-resume.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleV2ResumeSession = handleV2ResumeSession;
 const types_js_1 = require("../types.js");
-const output_schemas_js_1 = require("../output-schemas.js");
 const v2_token_ops_js_1 = require("./v2-token-ops.js");
 const index_js_1 = require("../../v2/durable-core/ids/index.js");
 const resume_session_js_1 = require("../../v2/usecases/resume-session.js");
@@ -43,10 +42,10 @@ async function handleV2ResumeSession(input, ctx) {
     if (skipped > 0) {
         console.error(`[workrail:resume] ${skipped}/${candidates.length} candidate(s) skipped: token minting failed (workflowHashRef derivation or signing error)`);
     }
-    const output = output_schemas_js_1.V2ResumeSessionOutputSchema.parse({
-        candidates: outputCandidates,
+    const output = {
+        candidates: [...outputCandidates],
         totalEligible: totalFound,
-    });
+    };
     return {
         type: 'success',
         data: output,

package/dist/mcp/handlers/v2-state-conversion.js

@@ -9,6 +9,7 @@ exports.derivePreferencesForNode = derivePreferencesForNode;
 exports.deriveNextIntent = deriveNextIntent;
 const step_instance_key_js_1 = require("../../v2/durable-core/schemas/execution-snapshot/step-instance-key.js");
 const preferences_js_1 = require("../../v2/projections/preferences.js");
+const sorted_event_log_js_1 = require("../../v2/durable-core/sorted-event-log.js");
 const constants_js_1 = require("../../v2/durable-core/constants.js");
 function toV1ExecutionState(engineState) {
     if (engineState.kind === 'init')
@@ -94,7 +95,10 @@ function derivePreferencesForNode(args) {
             continue;
         parentByNodeId[String(e.scope.nodeId)] = e.data.parentNodeId;
     }
-    const prefs = (0, preferences_js_1.projectPreferencesV2)(args.truth.events, parentByNodeId);
+    const sortedEventsRes = (0, sorted_event_log_js_1.asSortedEventLog)(args.truth.events);
+    if (sortedEventsRes.isErr())
+        return exports.defaultPreferences;
+    const prefs = (0, preferences_js_1.projectPreferencesV2)(sortedEventsRes.value, parentByNodeId);
     if (prefs.isErr())
         return exports.defaultPreferences;
     const p = prefs.value.byNodeId[String(args.nodeId)]?.effective;

package/dist/mcp/handlers/v2-workflow.d.ts

@@ -1,7 +1,107 @@
 import type { ToolContext, ToolResult } from '../types.js';
 import type { V2InspectWorkflowInput, V2ListWorkflowsInput } from '../v2/tools.js';
 import type { StalenessSummary } from '../output-schemas.js';
+import type { RememberedRootRecordV2 } from '../../v2/ports/remembered-roots-store.port.js';
+import type { CryptoPortV2 } from '../../v2/durable-core/canonical/hashing.js';
+import type { PinnedWorkflowStorePortV2 } from '../../v2/ports/pinned-workflow-store.port.js';
+import type { Workflow } from '../../types/workflow.js';
 export declare function shouldShowStaleness(category: string | undefined, devMode?: boolean): boolean;
+interface WorkflowTagsFile {
+    readonly tags: ReadonlyArray<{
+        readonly id: string;
+        readonly displayName: string;
+        readonly when: readonly string[];
+        readonly examples: readonly string[];
+    }>;
+    readonly workflows: Readonly<Record<string, {
+        readonly tags: readonly string[];
+        readonly hidden?: boolean;
+    }>>;
+}
+export declare function buildTagSummary(tagsFile: WorkflowTagsFile, compiledWorkflowIds: readonly string[]): Array<{
+    id: string;
+    displayName: string;
+    count: number;
+    when: string[];
+    examples: string[];
+}>;
 export declare function computeWorkflowStaleness(stamp: number | undefined, currentVersion: number | null): StalenessSummary | undefined;
+interface WorkflowLookupReader {
+    readonly getWorkflowById: (id: string) => Promise<Workflow | null>;
+    readonly listWorkflowSummaries: () => Promise<readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly description: string;
+        readonly version: string;
+    }[]>;
+    readonly loadAllWorkflows: () => Promise<readonly Workflow[]>;
+}
 export declare function handleV2ListWorkflows(input: V2ListWorkflowsInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
 export declare function handleV2InspectWorkflow(input: V2InspectWorkflowInput, ctx: ToolContext): Promise<ToolResult<unknown>>;
+export declare function buildV2WorkflowListItem(options: {
+    readonly workflow: Workflow | null;
+    readonly summary: {
+        readonly id: string;
+        readonly name: string;
+        readonly description: string;
+        readonly version: string;
+    };
+    readonly workflowReader: WorkflowLookupReader;
+    readonly rememberedRootRecords: readonly RememberedRootRecordV2[];
+    readonly crypto: CryptoPortV2;
+    readonly pinnedStore: PinnedWorkflowStorePortV2;
+}): Promise<{
+    workflowId: string;
+    name: string;
+    description: string;
+    version: string;
+    workflowHash: null;
+    kind: "workflow";
+} | {
+    examples: string[];
+    workflowId: string;
+    name: string;
+    description: string;
+    version: string;
+    workflowHash: null;
+    kind: "workflow";
+    visibility: import("./shared/workflow-source-visibility.js").WorkflowVisibility;
+} | {
+    examples?: undefined;
+    workflowId: string;
+    name: string;
+    description: string;
+    version: string;
+    workflowHash: null;
+    kind: "workflow";
+    visibility: import("./shared/workflow-source-visibility.js").WorkflowVisibility;
+} | {
+    examples: string[];
+    staleness?: {
+        level: "none" | "possible" | "likely";
+        reason: string;
+        specVersionAtLastReview?: number | undefined;
+    } | undefined;
+    workflowId: string;
+    name: string;
+    description: string;
+    version: string;
+    workflowHash: never;
+    kind: "workflow";
+    visibility: import("./shared/workflow-source-visibility.js").WorkflowVisibility;
+} | {
+    examples?: undefined;
+    staleness?: {
+        level: "none" | "possible" | "likely";
+        reason: string;
+        specVersionAtLastReview?: number | undefined;
+    } | undefined;
+    workflowId: string;
+    name: string;
+    description: string;
+    version: string;
+    workflowHash: never;
+    kind: "workflow";
+    visibility: import("./shared/workflow-source-visibility.js").WorkflowVisibility;
+}>;
+export {};

package/dist/mcp/handlers/v2-workflow.js

@@ -4,16 +4,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.shouldShowStaleness = shouldShowStaleness;
+exports.buildTagSummary = buildTagSummary;
 exports.computeWorkflowStaleness = computeWorkflowStaleness;
 exports.handleV2ListWorkflows = handleV2ListWorkflows;
 exports.handleV2InspectWorkflow = handleV2InspectWorkflow;
+exports.buildV2WorkflowListItem = buildV2WorkflowListItem;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const neverthrow_1 = require("neverthrow");
 const types_js_1 = require("../types.js");
 const error_mapper_js_1 = require("../error-mapper.js");
 const v2_execution_helpers_js_1 = require("./v2-execution-helpers.js");
-const output_schemas_js_1 = require("../output-schemas.js");
 const v1_to_v2_shim_js_1 = require("../../v2/read-only/v1-to-v2-shim.js");
 const hashing_js_1 = require("../../v2/durable-core/canonical/hashing.js");
 const TIMEOUT_MS = 30000;
@@ -40,6 +41,39 @@ function shouldShowStaleness(category, devMode = DEV_STALENESS) {
         return true;
     return category === 'personal' || category === 'rooted_sharing' || category === 'external';
 }
+function readWorkflowTags() {
+    try {
+        const tagsPath = path_1.default.resolve(__dirname, '../../../spec/workflow-tags.json');
+        const raw = fs_1.default.readFileSync(tagsPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+const WORKFLOW_TAGS = readWorkflowTags();
+function buildTagSummary(tagsFile, compiledWorkflowIds) {
+    const idSet = new Set(compiledWorkflowIds);
+    return tagsFile.tags.map((tag) => {
+        const count = Object.entries(tagsFile.workflows)
+            .filter(([wid, meta]) => !meta.hidden && idSet.has(wid) && meta.tags.includes(tag.id))
+            .length;
+        return {
+            id: tag.id,
+            displayName: tag.displayName,
+            count,
+            when: [...tag.when],
+            examples: [...tag.examples],
+        };
+    });
+}
+function filterByTags(tagsFile, compiledWorkflowIds, requestedTags) {
+    const tagSet = new Set(requestedTags);
+    const matching = new Set(Object.entries(tagsFile.workflows)
+        .filter(([, meta]) => !meta.hidden && meta.tags.some((t) => tagSet.has(t)))
+        .map(([wid]) => wid));
+    return compiledWorkflowIds.filter((id) => matching.has(id));
+}
 function computeWorkflowStaleness(stamp, currentVersion) {
     if (currentVersion === null)
         return undefined;
@@ -90,40 +124,94 @@ async function handleV2ListWorkflows(input, ctx) {
             workspacePath: input.workspacePath,
             resolvedRootUris: guard.ctx.v2.resolvedRootUris,
             rememberedRootsStore: guard.ctx.v2.rememberedRootsStore,
+            managedSourceStore: guard.ctx.v2.managedSourceStore,
         })
-        : { reader: ctx.workflowService, stalePaths: [] };
+        : { reader: ctx.workflowService, stalePaths: [], managedSourceRecords: [], staleManagedRecords: [], managedStoreError: undefined };
     const workflowReader = readerResult.reader;
     const stalePaths = readerResult.stalePaths;
-    return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(workflowReader.listWorkflowSummaries(), TIMEOUT_MS, 'list_workflows'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
-        .andThen((summaries) => neverthrow_1.ResultAsync.combine(summaries.map((s) => neverthrow_1.ResultAsync.fromPromise(buildV2WorkflowListItem({
-        summary: s,
-        workflowReader,
-        rememberedRootRecords,
-        crypto,
-        pinnedStore,
-    }), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err)))))
+    const managedSourceRecords = readerResult.managedSourceRecords;
+    const staleManagedRecords = readerResult.staleManagedRecords;
+    const managedStoreError = readerResult.managedStoreError;
+    const warnings = managedStoreError
+        ? [`Managed workflow source store was temporarily unavailable (${managedStoreError}). Managed sources were not loaded.`]
+        : undefined;
+    return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(workflowReader.loadAllWorkflows(), TIMEOUT_MS, 'list_workflows'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
+        .andThen((allWorkflows) => {
+        const workflowMap = new Map(allWorkflows.map((w) => [w.definition.id, w]));
+        const summaries = allWorkflows.map((w) => ({
+            id: w.definition.id,
+            name: w.definition.name,
+            description: w.definition.description,
+            version: w.definition.version,
+        }));
+        return neverthrow_1.ResultAsync.combine(summaries.map((s) => neverthrow_1.ResultAsync.fromPromise(buildV2WorkflowListItem({
+            workflow: workflowMap.get(s.id) ?? null,
+            summary: s,
+            workflowReader,
+            rememberedRootRecords,
+            crypto,
+            pinnedStore,
+        }), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))));
+    })
         .andThen((compiled) => {
+        const sortedIds = compiled.map((w) => w.workflowId).sort((a, b) => a.localeCompare(b));
+        const sortedCompiled = [...compiled].sort((a, b) => a.workflowId.localeCompare(b.workflowId));
+        const tagFilteredCompiled = (() => {
+            if (input.includeSources)
+                return sortedCompiled;
+            if (!WORKFLOW_TAGS)
+                return sortedCompiled;
+            if (input.tags && input.tags.length > 0) {
+                const filteredIds = new Set(filterByTags(WORKFLOW_TAGS, sortedIds, input.tags));
+                return sortedCompiled.filter((w) => filteredIds.has(w.workflowId));
+            }
+            return [];
+        })();
+        const tagSummaryEntry = (() => {
+            if (input.includeSources)
+                return undefined;
+            if (!WORKFLOW_TAGS)
+                return undefined;
+            if (input.tags && input.tags.length > 0)
+                return undefined;
+            return buildTagSummary(WORKFLOW_TAGS, sortedIds);
+        })();
+        const nextStepHint = tagSummaryEntry
+            ? 'Pick a tag from tagSummary that fits the user\'s goal, then call list_workflows with tags=["<tagId>"]. ' +
+                'If a workflow ID in examples[] already matches, call start_workflow directly — no second list call needed. ' +
+                'If multiple tags could apply, pick the most specific one.'
+            : undefined;
         if (!input.includeSources) {
-            const payload = output_schemas_js_1.V2WorkflowListOutputSchema.parse({
-                workflows: compiled.sort((a, b) => a.workflowId.localeCompare(b.workflowId)),
-                ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
-            });
+            const includeStaleRoots = !tagSummaryEntry && stalePaths.length > 0;
+            const payload = {
+                workflows: tagFilteredCompiled,
+                ...(tagSummaryEntry ? { tagSummary: tagSummaryEntry } : {}),
+                ...(nextStepHint ? { _nextStep: nextStepHint } : {}),
+                ...(includeStaleRoots ? { staleRoots: [...stalePaths] } : {}),
+                ...(warnings ? { warnings } : {}),
+            };
             return (0, neverthrow_1.okAsync)((0, types_js_1.success)(payload));
         }
         if (!(0, workflow_source_visibility_js_1.isCompositeWorkflowReader)(workflowReader)) {
-            const payload = output_schemas_js_1.V2WorkflowListOutputSchema.parse({
-                workflows: compiled.sort((a, b) => a.workflowId.localeCompare(b.workflowId)),
+            const payload = {
+                workflows: tagFilteredCompiled,
+                ...(tagSummaryEntry ? { tagSummary: tagSummaryEntry } : {}),
+                ...(nextStepHint ? { _nextStep: nextStepHint } : {}),
                 ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
+                ...(warnings ? { warnings } : {}),
                 sources: [],
-            });
+            };
             return (0, neverthrow_1.okAsync)((0, types_js_1.success)(payload));
         }
-        return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(buildSourceCatalog(workflowReader, rememberedRootRecords), TIMEOUT_MS, 'list_workflow_sources'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err)).map((sources) => {
-            const payload = output_schemas_js_1.V2WorkflowListOutputSchema.parse({
-                workflows: compiled.sort((a, b) => a.workflowId.localeCompare(b.workflowId)),
+        return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(buildSourceCatalog(workflowReader, rememberedRootRecords, managedSourceRecords, staleManagedRecords), TIMEOUT_MS, 'list_workflow_sources'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err)).map((sources) => {
+            const payload = {
+                workflows: tagFilteredCompiled,
+                ...(tagSummaryEntry ? { tagSummary: tagSummaryEntry } : {}),
+                ...(nextStepHint ? { _nextStep: nextStepHint } : {}),
                 ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
-                sources,
-            });
+                ...(warnings ? { warnings } : {}),
+                sources: [...sources],
+            };
             return (0, types_js_1.success)(payload);
         });
     })
@@ -150,10 +238,14 @@ async function handleV2InspectWorkflow(input, ctx) {
             workspacePath: input.workspacePath,
             resolvedRootUris: guard.ctx.v2.resolvedRootUris,
             rememberedRootsStore: guard.ctx.v2.rememberedRootsStore,
+            managedSourceStore: guard.ctx.v2.managedSourceStore,
         })
-        : { reader: ctx.workflowService, stalePaths: [] };
+        : { reader: ctx.workflowService, stalePaths: [], managedSourceRecords: [], staleManagedRecords: [], managedStoreError: undefined };
     const workflowReader = readerResult.reader;
     const stalePaths = readerResult.stalePaths;
+    const inspectWarnings = readerResult.managedStoreError
+        ? [`Managed workflow source store was temporarily unavailable (${readerResult.managedStoreError}). Managed sources were not loaded.`]
+        : undefined;
     return neverthrow_1.ResultAsync.fromPromise((0, with_timeout_js_1.withTimeout)(workflowReader.getWorkflowById(input.workflowId), TIMEOUT_MS, 'inspect_workflow'), (err) => (0, error_mapper_js_1.mapUnknownErrorToToolError)(err))
         .andThen((workflow) => {
         if (!workflow) {
@@ -182,21 +274,22 @@ async function handleV2InspectWorkflow(input, ctx) {
                 ? { schemaVersion: compiled.schemaVersion, sourceKind: compiled.sourceKind, workflowId: compiled.workflowId }
                 : compiled;
             const references = workflow.definition.references;
-            const payload = output_schemas_js_1.V2WorkflowInspectOutputSchema.parse({
+            const payload = {
                 workflowId: input.workflowId,
                 workflowHash,
                 mode: input.mode,
                 compiled: body,
                 ...(visibility ? { visibility } : {}),
                 ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
-                ...(references != null && references.length > 0 ? { references } : {}),
+                ...(inspectWarnings ? { warnings: inspectWarnings } : {}),
+                ...(references != null && references.length > 0 ? { references: [...references] } : {}),
                 ...(() => {
                     const staleness = shouldShowStaleness(visibility?.category)
                         ? computeWorkflowStaleness(workflow.definition.validatedAgainstSpecVersion, CURRENT_SPEC_VERSION)
                         : undefined;
                     return staleness !== undefined ? { staleness } : {};
                 })(),
-            });
+            };
             return (0, neverthrow_1.okAsync)((0, types_js_1.success)(payload));
         }));
     })
@@ -211,8 +304,7 @@ async function buildWorkflowVisibility(workflow, workflowReader, rememberedRootR
     return (0, workflow_source_visibility_js_1.toWorkflowVisibility)(workflow, rememberedRootRecords, { migration });
 }
 async function buildV2WorkflowListItem(options) {
-    const { summary, workflowReader, rememberedRootRecords, crypto, pinnedStore } = options;
-    const workflow = await workflowReader.getWorkflowById(summary.id);
+    const { workflow, summary, workflowReader, rememberedRootRecords, crypto, pinnedStore } = options;
     if (!workflow) {
         return {
             workflowId: summary.id,
@@ -224,6 +316,9 @@ async function buildV2WorkflowListItem(options) {
         };
     }
     const visibility = await buildWorkflowVisibility(workflow, workflowReader, rememberedRootRecords);
+    const examples = workflow.definition.examples?.length
+        ? { examples: [...workflow.definition.examples] }
+        : {};
     const snapshot = (0, v1_to_v2_shim_js_1.compileV1WorkflowToV2PreviewSnapshot)(workflow);
     const hashRes = (0, hashing_js_1.workflowHashForCompiledSnapshot)(snapshot, crypto);
     if (hashRes.isErr()) {
@@ -235,6 +330,7 @@ async function buildV2WorkflowListItem(options) {
             workflowHash: null,
             kind: 'workflow',
             visibility,
+            ...examples,
         };
     }
     const hash = hashRes.value;
@@ -250,6 +346,7 @@ async function buildV2WorkflowListItem(options) {
                 workflowHash: hash,
                 kind: 'workflow',
                 visibility,
+                ...examples,
             };
         }
     }
@@ -265,9 +362,10 @@ async function buildV2WorkflowListItem(options) {
         kind: 'workflow',
         visibility,
         ...(staleness !== undefined ? { staleness } : {}),
+        ...examples,
     };
 }
-async function buildSourceCatalog(workflowReader, rememberedRootRecords) {
+async function buildSourceCatalog(workflowReader, rememberedRootRecords, managedSourceRecords, staleManagedRecords) {
     const instances = workflowReader.getStorageInstances();
     const seenIds = new Set();
     const sourceEntryDataReversed = [];
@@ -281,10 +379,22 @@ async function buildSourceCatalog(workflowReader, rememberedRootRecords) {
         sourceEntryDataReversed.push({ source: instance.source, allIds, effectiveIds });
     }
     const sourceEntryData = sourceEntryDataReversed.reverse();
-    return sourceEntryData.map((data) => deriveSourceCatalogEntry({ ...data, rememberedRootRecords, sourceEntryData }));
+    const activeEntries = sourceEntryData.map((data) => deriveSourceCatalogEntry({ ...data, rememberedRootRecords, managedSourceRecords, sourceEntryData }));
+    const staleEntries = staleManagedRecords.map((record) => ({
+        sourceKey: `custom:${record.path}`,
+        category: 'managed',
+        source: { kind: 'custom', displayName: path_1.default.basename(record.path) },
+        sourceMode: 'live_directory',
+        effectiveWorkflowCount: 0,
+        totalWorkflowCount: 0,
+        shadowedWorkflowCount: 0,
+        managed: { addedAtMs: record.addedAtMs },
+        stale: true,
+    }));
+    return [...activeEntries, ...staleEntries];
 }
 function deriveSourceCatalogEntry(options) {
-    const { source, allIds, effectiveIds, rememberedRootRecords, sourceEntryData } = options;
+    const { source, allIds, effectiveIds, rememberedRootRecords, managedSourceRecords, sourceEntryData } = options;
     const total = allIds.length;
     const effective = effectiveIds.length;
     const shadowed = total - effective;
@@ -310,6 +420,20 @@ function deriveSourceCatalogEntry(options) {
         }
         case 'custom': {
             const rootedSharing = deriveRootedSharingForPath(source.directoryPath, rememberedRootRecords);
+            const managedRecord = managedSourceRecords.find((r) => path_1.default.resolve(r.path) === path_1.default.resolve(source.directoryPath));
+            if (managedRecord) {
+                return {
+                    sourceKey,
+                    category: 'managed',
+                    source: { kind: source.kind, displayName },
+                    sourceMode: 'live_directory',
+                    effectiveWorkflowCount: effective,
+                    totalWorkflowCount: total,
+                    shadowedWorkflowCount: shadowed,
+                    managed: { addedAtMs: managedRecord.addedAtMs },
+                    ...(rootedSharing ? { rootedSharing } : {}),
+                };
+            }
             const category = rootedSharing ? 'rooted_sharing' : 'external';
             const sourceMode = rootedSharing ? 'rooted_sharing' : 'live_directory';
             return { sourceKey, category, source: { kind: source.kind, displayName }, sourceMode, effectiveWorkflowCount: effective, totalWorkflowCount: total, shadowedWorkflowCount: shadowed, ...(rootedSharing ? { rootedSharing } : {}) };