@exaudeus/workrail 3.13.0 → 3.15.0

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

@@ -3,9 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldShowStaleness = shouldShowStaleness;
+exports.buildTagSummary = buildTagSummary;
+exports.computeWorkflowStaleness = computeWorkflowStaleness;
 exports.handleV2ListWorkflows = handleV2ListWorkflows;
 exports.handleV2InspectWorkflow = handleV2InspectWorkflow;
 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");
@@ -14,6 +18,84 @@ 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;
+function readCurrentSpecVersion() {
+    try {
+        const specPath = path_1.default.resolve(__dirname, '../../../spec/authoring-spec.json');
+        const raw = fs_1.default.readFileSync(specPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' && parsed !== null && 'version' in parsed) {
+            const v = parsed['version'];
+            if (typeof v === 'number' && Number.isInteger(v) && v >= 1)
+                return v;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+const CURRENT_SPEC_VERSION = readCurrentSpecVersion();
+const DEV_STALENESS = process.env['WORKRAIL_DEV_STALENESS'] === '1';
+function shouldShowStaleness(category, devMode = DEV_STALENESS) {
+    if (devMode)
+        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;
+    if (stamp === undefined) {
+        return {
+            level: 'possible',
+            reason: 'This workflow has not been validated against the authoring spec via workflow-for-workflows.',
+        };
+    }
+    if (stamp === currentVersion) {
+        return {
+            level: 'none',
+            reason: `Workflow validated against current authoring spec (v${currentVersion}).`,
+            specVersionAtLastReview: stamp,
+        };
+    }
+    return {
+        level: 'likely',
+        reason: `Authoring spec updated from v${stamp} to v${currentVersion} since this workflow was last reviewed.`,
+        specVersionAtLastReview: stamp,
+    };
+}
 const with_timeout_js_1 = require("./shared/with-timeout.js");
 const request_workflow_reader_js_1 = require("./shared/request-workflow-reader.js");
 const remembered_roots_js_1 = require("./shared/remembered-roots.js");
@@ -42,10 +124,17 @@ 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;
+    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.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,
@@ -55,25 +144,62 @@ async function handleV2ListWorkflows(input, ctx) {
         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 includeStaleRoots = !tagSummaryEntry && stalePaths.length > 0;
             const payload = output_schemas_js_1.V2WorkflowListOutputSchema.parse({
-                workflows: compiled.sort((a, b) => a.workflowId.localeCompare(b.workflowId)),
-                ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
+                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)),
+                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) => {
+        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 = output_schemas_js_1.V2WorkflowListOutputSchema.parse({
-                workflows: compiled.sort((a, b) => a.workflowId.localeCompare(b.workflowId)),
+                workflows: tagFilteredCompiled,
+                ...(tagSummaryEntry ? { tagSummary: tagSummaryEntry } : {}),
+                ...(nextStepHint ? { _nextStep: nextStepHint } : {}),
                 ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
+                ...(warnings ? { warnings } : {}),
                 sources,
             });
             return (0, types_js_1.success)(payload);
@@ -102,10 +228,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) {
@@ -141,7 +271,14 @@ async function handleV2InspectWorkflow(input, ctx) {
                 compiled: body,
                 ...(visibility ? { visibility } : {}),
                 ...(stalePaths.length > 0 ? { staleRoots: [...stalePaths] } : {}),
+                ...(inspectWarnings ? { warnings: inspectWarnings } : {}),
                 ...(references != null && references.length > 0 ? { 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));
         }));
@@ -199,6 +336,9 @@ async function buildV2WorkflowListItem(options) {
             };
         }
     }
+    const staleness = shouldShowStaleness(visibility?.category)
+        ? computeWorkflowStaleness(workflow.definition.validatedAgainstSpecVersion, CURRENT_SPEC_VERSION)
+        : undefined;
     return {
         workflowId: summary.id,
         name: summary.name,
@@ -207,9 +347,10 @@ async function buildV2WorkflowListItem(options) {
         workflowHash: hash,
         kind: 'workflow',
         visibility,
+        ...(staleness !== undefined ? { staleness } : {}),
     };
 }
-async function buildSourceCatalog(workflowReader, rememberedRootRecords) {
+async function buildSourceCatalog(workflowReader, rememberedRootRecords, managedSourceRecords, staleManagedRecords) {
     const instances = workflowReader.getStorageInstances();
     const seenIds = new Set();
     const sourceEntryDataReversed = [];
@@ -223,10 +364,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;
@@ -252,6 +405,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 } : {}) };