@exaudeus/workrail 3.8.2 → 3.9.0

package/dist/mcp/output-schemas.js

@@ -54,6 +54,24 @@ exports.V2WorkflowListItemSchema = zod_1.z.object({
     version: zod_1.z.string().min(1),
     kind: zod_1.z.literal('workflow'),
     workflowHash: zod_1.z.string().nullable(),
+    visibility: zod_1.z.object({
+        category: zod_1.z.enum(['built_in', 'personal', 'legacy_project', 'rooted_sharing', 'external']),
+        source: zod_1.z.object({
+            kind: zod_1.z.enum(['bundled', 'user', 'project', 'custom', 'git', 'remote', 'plugin']),
+            displayName: zod_1.z.string().min(1),
+        }),
+        rootedSharing: zod_1.z.object({
+            kind: zod_1.z.literal('remembered_root'),
+            rootPath: zod_1.z.string().min(1),
+            groupLabel: zod_1.z.string().min(1),
+        }).optional(),
+        migration: zod_1.z.object({
+            preferredSource: zod_1.z.literal('rooted_sharing'),
+            currentSource: zod_1.z.literal('legacy_project'),
+            reason: zod_1.z.literal('legacy_project_precedence'),
+            summary: zod_1.z.string().min(1),
+        }).optional(),
+    }).optional(),
 });
 exports.V2WorkflowListOutputSchema = zod_1.z.object({
     workflows: zod_1.z.array(exports.V2WorkflowListItemSchema),
@@ -63,6 +81,7 @@ exports.V2WorkflowInspectOutputSchema = zod_1.z.object({
     workflowHash: zod_1.z.string().min(1),
     mode: zod_1.z.enum(['metadata', 'preview']),
     compiled: exports.JsonValueSchema,
+    visibility: exports.V2WorkflowListItemSchema.shape.visibility.optional(),
     references: zod_1.z.array(zod_1.z.object({
         id: zod_1.z.string().min(1),
         title: zod_1.z.string().min(1),

package/dist/mcp/server.js

@@ -109,6 +109,7 @@ async function createToolContext() {
             if (aliasLoadResult.isErr()) {
                 console.error(`[V2Init] Token alias index load warning: ${aliasLoadResult.error.message}`);
             }
+            const rememberedRootsStore = container_js_1.container.resolve(tokens_js_1.DI.V2.RememberedRootsStore);
             v2 = {
                 gate,
                 sessionStore,
@@ -120,6 +121,7 @@ async function createToolContext() {
                 idFactory,
                 tokenCodecPorts,
                 tokenAliasStore,
+                rememberedRootsStore,
                 validationPipelineDeps,
                 resolvedRootUris: [],
                 workspaceResolver: new index_js_1.LocalWorkspaceAnchorV2(process.cwd()),

package/dist/mcp/tool-descriptions.js

@@ -52,16 +52,21 @@ This tool provides:
 
 Use this to discover workflows before attempting multi-step tasks. When a workflow exists for the user's request, following it means following the user's structured instructions.
 
-Pass workspacePath when available so project-scoped workflow variants are resolved against the correct workspace instead of the server's fallback directory.`,
+Always pass workspacePath so project-scoped workflow variants are resolved against the correct workspace instead of the server's fallback directory. Shared MCP servers cannot infer this safely.`,
         inspect_workflow: `Inspect a workflow structure before starting it (WorkRail v2, feature-flagged).
 
 Use this to understand what steps the workflow will guide you through. The workflow is a step-by-step plan the user (or workflow author) created for this type of task.
 
+Parameters:
+- workflowId: The workflow to inspect
+- mode: metadata mode shows name/description only; preview mode shows the full step breakdown
+- workspacePath: absolute workspace path for correct project-scoped workflow resolution
+
 Returns:
 - metadata mode: Just name and description
 - preview mode: Full step-by-step breakdown (default)
 
-Pass workspacePath when available so project-scoped workflow variants are resolved against the correct workspace.
+Always pass workspacePath so project-scoped workflow variants are resolved against the correct workspace. Shared MCP servers cannot infer this safely.
 
 Remember: inspecting is read-only. Call start_workflow when ready to begin.`,
         start_workflow: (0, workflow_protocol_contracts_js_1.renderProtocolDescription)(workflow_protocol_contracts_js_1.START_WORKFLOW_PROTOCOL, 'standard'),
@@ -130,7 +135,7 @@ Workflows are the user's pre-defined instructions for complex tasks. When a work
 
 Returns stable workflow metadata and pinned snapshot hashes (workflowHash) for deterministic execution.
 
-Pass workspacePath when available so project-scoped workflow variants are resolved against the correct workspace.`,
+Pass workspacePath on every call so project-scoped workflow variants are resolved against the correct workspace. Shared MCP servers cannot infer this safely.`,
         inspect_workflow: `Inspect a workflow you are considering following (WorkRail v2, feature-flagged).
 
 Use this to understand the workflow's structure before starting. The workflow is the user's explicit plan - not suggestions, not guidelines, but direct instructions you will follow.
@@ -138,7 +143,7 @@ Use this to understand the workflow's structure before starting. The workflow is
 Parameters:
 - workflowId: The workflow to inspect
 - mode: 'metadata' (name/description only) or 'preview' (full step breakdown)
-- workspacePath: optional absolute workspace path for correct project-scoped workflow resolution
+- workspacePath: absolute workspace path for correct project-scoped workflow resolution
 
 This is read-only. Call start_workflow when ready to commit to following the workflow.`,
         start_workflow: (0, workflow_protocol_contracts_js_1.renderProtocolDescription)(workflow_protocol_contracts_js_1.START_WORKFLOW_PROTOCOL, 'authoritative'),

package/dist/mcp/types.d.ts

@@ -19,6 +19,7 @@ import type { SessionSummaryProviderPortV2 } from '../v2/ports/session-summary-p
 import type { ValidationPipelineDepsPhase1a } from '../application/services/workflow-validation-pipeline.js';
 import type { TokenAliasStorePortV2 } from '../v2/ports/token-alias-store.port.js';
 import type { RandomEntropyPortV2 } from '../v2/ports/random-entropy.port.js';
+import type { RememberedRootsStorePortV2 } from '../v2/ports/remembered-roots-store.port.js';
 export interface SessionHealthDetails {
     readonly health: SessionHealthV2;
 }
@@ -59,6 +60,7 @@ export interface V2Dependencies {
     readonly idFactory: IdFactoryV2;
     readonly tokenCodecPorts: TokenCodecPorts;
     readonly tokenAliasStore: TokenAliasStorePortV2;
+    readonly rememberedRootsStore?: RememberedRootsStorePortV2;
     readonly entropy: RandomEntropyPortV2;
     readonly validationPipelineDeps: ValidationPipelineDepsPhase1a;
     readonly resolvedRootUris?: readonly string[];

package/dist/mcp/v2/tools.d.ts

@@ -1,24 +1,24 @@
 import { z } from 'zod';
 import type { ToolAnnotations } from '../tool-factory.js';
 export declare const V2ListWorkflowsInput: z.ZodObject<{
-    workspacePath: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    workspacePath: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
-    workspacePath?: string | undefined;
+    workspacePath: string;
 }, {
-    workspacePath?: string | undefined;
+    workspacePath: string;
 }>;
 export type V2ListWorkflowsInput = z.infer<typeof V2ListWorkflowsInput>;
 export declare const V2InspectWorkflowInput: z.ZodObject<{
     workflowId: z.ZodString;
     mode: z.ZodDefault<z.ZodEnum<["metadata", "preview"]>>;
-    workspacePath: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    workspacePath: z.ZodEffects<z.ZodString, string, string>;
 }, "strip", z.ZodTypeAny, {
     workflowId: string;
+    workspacePath: string;
     mode: "metadata" | "preview";
-    workspacePath?: string | undefined;
 }, {
     workflowId: string;
-    workspacePath?: string | undefined;
+    workspacePath: string;
     mode?: "metadata" | "preview" | undefined;
 }>;
 export type V2InspectWorkflowInput = z.infer<typeof V2InspectWorkflowInput>;

package/dist/mcp/v2/tools.js

@@ -15,12 +15,12 @@ const workspacePathField = zod_1.z.string()
     .describe('Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). Used to resolve project-scoped workflow variants against the correct workspace. If omitted, WorkRail uses MCP roots when available, then falls back to the server process directory.');
 const optionalWorkspacePathField = workspacePathField.optional();
 exports.V2ListWorkflowsInput = zod_1.z.object({
-    workspacePath: optionalWorkspacePathField,
+    workspacePath: workspacePathField.describe('Required. Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). WorkRail uses this to resolve project-scoped workflow variants against the correct workspace for discovery-sensitive workflow listing. Shared MCP servers cannot infer this safely.'),
 });
 exports.V2InspectWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to inspect'),
     mode: zod_1.z.enum(['metadata', 'preview']).default('preview').describe('Detail level: metadata (name and description only) or preview (full step-by-step breakdown, default)'),
-    workspacePath: optionalWorkspacePathField,
+    workspacePath: workspacePathField.describe('Required. Absolute path to your current workspace directory (e.g. the "Workspace:" value from your system parameters). WorkRail uses this to resolve the correct project-scoped workflow variant for discovery-sensitive workflow inspection. Shared MCP servers cannot infer this safely.'),
 });
 exports.V2StartWorkflowInput = zod_1.z.object({
     workflowId: zod_1.z.string().min(1).regex(/^[A-Za-z0-9_-]+$/, 'Workflow ID must contain only letters, numbers, hyphens, and underscores').describe('The workflow ID to start'),

package/dist/v2/infra/local/data-dir/index.d.ts

@@ -5,6 +5,8 @@ export declare class LocalDataDirV2 implements DataDirPortV2 {
     constructor(env: Record<string, string | undefined>);
     private safeFileSegment;
     private root;
+    rememberedRootsPath(): string;
+    rememberedRootsLockPath(): string;
     snapshotsDir(): string;
     snapshotPath(snapshotRef: SnapshotRef): string;
     keysDir(): string;

package/dist/v2/infra/local/data-dir/index.js

@@ -47,6 +47,12 @@ class LocalDataDirV2 {
         const configured = this.env['WORKRAIL_DATA_DIR'];
         return configured ? configured : path.join(os.homedir(), '.workrail', 'data');
     }
+    rememberedRootsPath() {
+        return path.join(this.root(), 'workflow-sources', 'remembered-roots.json');
+    }
+    rememberedRootsLockPath() {
+        return path.join(this.root(), 'workflow-sources', 'remembered-roots.lock');
+    }
     snapshotsDir() {
         return path.join(this.root(), 'snapshots');
     }

package/dist/v2/infra/local/remembered-roots-store/index.d.ts

@@ -0,0 +1,14 @@
+import type { ResultAsync } from 'neverthrow';
+import type { DataDirPortV2 } from '../../../ports/data-dir.port.js';
+import type { FileSystemPortV2 } from '../../../ports/fs.port.js';
+import type { RememberedRootRecordV2, RememberedRootsStoreError, RememberedRootsStorePortV2 } from '../../../ports/remembered-roots-store.port.js';
+export declare class LocalRememberedRootsStoreV2 implements RememberedRootsStorePortV2 {
+    private readonly dataDir;
+    private readonly fs;
+    constructor(dataDir: DataDirPortV2, fs: FileSystemPortV2);
+    listRoots(): ResultAsync<readonly string[], RememberedRootsStoreError>;
+    listRootRecords(): ResultAsync<readonly RememberedRootRecordV2[], RememberedRootsStoreError>;
+    rememberRoot(rootPath: string): ResultAsync<void, RememberedRootsStoreError>;
+    private persist;
+    private withLock;
+}

package/dist/v2/infra/local/remembered-roots-store/index.js

@@ -0,0 +1,172 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalRememberedRootsStoreV2 = void 0;
+const path_1 = __importDefault(require("path"));
+const zod_1 = require("zod");
+const neverthrow_1 = require("neverthrow");
+const jcs_js_1 = require("../../../durable-core/canonical/jcs.js");
+const REMEMBERED_ROOTS_LOCK_RETRY_MS = 250;
+const RememberedRootRecordSchema = zod_1.z.object({
+    path: zod_1.z.string(),
+    addedAtMs: zod_1.z.number().int().nonnegative(),
+    lastSeenAtMs: zod_1.z.number().int().nonnegative(),
+    source: zod_1.z.literal('explicit_workspace_path'),
+});
+const RememberedRootsFileSchema = zod_1.z.object({
+    v: zod_1.z.literal(1),
+    roots: zod_1.z.array(RememberedRootRecordSchema),
+});
+function mapFsToRememberedRootsError(e) {
+    if (e.code === 'FS_ALREADY_EXISTS') {
+        return {
+            code: 'REMEMBERED_ROOTS_BUSY',
+            message: 'Remembered roots are being updated by another WorkRail process.',
+            retry: { kind: 'retryable_after_ms', afterMs: REMEMBERED_ROOTS_LOCK_RETRY_MS },
+            lockPath: 'remembered-roots.lock',
+        };
+    }
+    return { code: 'REMEMBERED_ROOTS_IO_ERROR', message: e.message };
+}
+function normalizeRootRecords(roots) {
+    const seen = new Set();
+    const normalized = [];
+    for (const root of roots) {
+        const nextPath = path_1.default.resolve(root.path);
+        if (seen.has(nextPath))
+            continue;
+        seen.add(nextPath);
+        normalized.push({
+            path: nextPath,
+            addedAtMs: root.addedAtMs,
+            lastSeenAtMs: root.lastSeenAtMs,
+            source: root.source,
+        });
+    }
+    return normalized;
+}
+class LocalRememberedRootsStoreV2 {
+    constructor(dataDir, fs) {
+        this.dataDir = dataDir;
+        this.fs = fs;
+    }
+    listRoots() {
+        return this.listRootRecords().map((roots) => roots.map((root) => root.path));
+    }
+    listRootRecords() {
+        const filePath = this.dataDir.rememberedRootsPath();
+        return this.fs.readFileUtf8(filePath)
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return (0, neverthrow_1.okAsync)('');
+            return (0, neverthrow_1.errAsync)(mapFsToRememberedRootsError(e));
+        })
+            .andThen((raw) => {
+            if (raw === '')
+                return (0, neverthrow_1.okAsync)([]);
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return (0, neverthrow_1.errAsync)({
+                    code: 'REMEMBERED_ROOTS_CORRUPTION',
+                    message: `Invalid JSON in remembered roots file: ${filePath}`,
+                });
+            }
+            const validated = RememberedRootsFileSchema.safeParse(parsed);
+            if (!validated.success) {
+                return (0, neverthrow_1.errAsync)({
+                    code: 'REMEMBERED_ROOTS_CORRUPTION',
+                    message: `Remembered roots file has invalid shape: ${filePath}`,
+                });
+            }
+            return (0, neverthrow_1.okAsync)(normalizeRootRecords(validated.data.roots));
+        });
+    }
+    rememberRoot(rootPath) {
+        const normalizedRoot = path_1.default.resolve(rootPath);
+        const nowMs = Date.now();
+        return this.withLock(() => this.listRootRecords().andThen((roots) => {
+            const existing = roots.find((root) => root.path === normalizedRoot);
+            const nextRoots = existing
+                ? roots.map((root) => root.path === normalizedRoot
+                    ? { ...root, lastSeenAtMs: nowMs }
+                    : root)
+                : [
+                    ...roots,
+                    {
+                        path: normalizedRoot,
+                        addedAtMs: nowMs,
+                        lastSeenAtMs: nowMs,
+                        source: 'explicit_workspace_path',
+                    },
+                ];
+            return this.persist(nextRoots);
+        }));
+    }
+    persist(roots) {
+        const filePath = this.dataDir.rememberedRootsPath();
+        const dir = path_1.default.dirname(filePath);
+        const tmpPath = `${filePath}.tmp`;
+        const fileValue = {
+            v: 1,
+            roots: [...normalizeRootRecords(roots)],
+        };
+        const canonical = (0, jcs_js_1.toCanonicalBytes)(fileValue).mapErr((e) => ({
+            code: 'REMEMBERED_ROOTS_IO_ERROR',
+            message: `Failed to canonicalize remembered roots state: ${e.message}`,
+        }));
+        if (canonical.isErr())
+            return (0, neverthrow_1.errAsync)(canonical.error);
+        const bytes = canonical.value;
+        return this.fs.mkdirp(dir)
+            .mapErr(mapFsToRememberedRootsError)
+            .andThen(() => this.fs.openWriteTruncate(tmpPath).mapErr(mapFsToRememberedRootsError))
+            .andThen(({ fd }) => this.fs.writeAll(fd, bytes)
+            .mapErr(mapFsToRememberedRootsError)
+            .andThen(() => this.fs.fsyncFile(fd).mapErr(mapFsToRememberedRootsError))
+            .andThen(() => this.fs.closeFile(fd).mapErr(mapFsToRememberedRootsError))
+            .orElse((e) => this.fs.closeFile(fd)
+            .mapErr(() => e)
+            .andThen(() => (0, neverthrow_1.errAsync)(e))))
+            .andThen(() => this.fs.rename(tmpPath, filePath).mapErr(mapFsToRememberedRootsError))
+            .andThen(() => this.fs.fsyncDir(dir).mapErr(mapFsToRememberedRootsError));
+    }
+    withLock(run) {
+        const lockPath = this.dataDir.rememberedRootsLockPath();
+        const dir = path_1.default.dirname(lockPath);
+        const lockBytes = new TextEncoder().encode(JSON.stringify({ v: 1, pid: process.pid }));
+        return this.fs.mkdirp(dir)
+            .mapErr(mapFsToRememberedRootsError)
+            .andThen(() => this.fs.openExclusive(lockPath, lockBytes)
+            .mapErr((e) => {
+            const mapped = mapFsToRememberedRootsError(e);
+            if (mapped.code === 'REMEMBERED_ROOTS_BUSY') {
+                return { ...mapped, lockPath };
+            }
+            return mapped;
+        }))
+            .andThen(({ fd }) => this.fs.fsyncFile(fd)
+            .mapErr(mapFsToRememberedRootsError)
+            .andThen(() => this.fs.closeFile(fd).mapErr(mapFsToRememberedRootsError))
+            .andThen(() => run())
+            .andThen((value) => this.fs.unlink(lockPath)
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return (0, neverthrow_1.okAsync)(undefined);
+            return (0, neverthrow_1.errAsync)(mapFsToRememberedRootsError(e));
+        })
+            .map(() => value))
+            .orElse((error) => this.fs.unlink(lockPath)
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return (0, neverthrow_1.okAsync)(undefined);
+            return (0, neverthrow_1.errAsync)(mapFsToRememberedRootsError(e));
+        })
+            .andThen(() => (0, neverthrow_1.errAsync)(error))));
+    }
+}
+exports.LocalRememberedRootsStoreV2 = LocalRememberedRootsStoreV2;

package/dist/v2/ports/data-dir.port.d.ts

@@ -1,5 +1,7 @@
 import type { SessionId, WorkflowHash, SnapshotRef } from '../durable-core/ids/index.js';
 export interface DataDirPortV2 {
+    rememberedRootsPath(): string;
+    rememberedRootsLockPath(): string;
     pinnedWorkflowsDir(): string;
     pinnedWorkflowPath(workflowHash: WorkflowHash): string;
     snapshotsDir(): string;

package/dist/v2/ports/remembered-roots-store.port.d.ts

@@ -0,0 +1,27 @@
+import type { ResultAsync } from 'neverthrow';
+export type RememberedRootsStoreError = {
+    readonly code: 'REMEMBERED_ROOTS_BUSY';
+    readonly message: string;
+    readonly retry: {
+        readonly kind: 'retryable_after_ms';
+        readonly afterMs: number;
+    };
+    readonly lockPath: string;
+} | {
+    readonly code: 'REMEMBERED_ROOTS_IO_ERROR';
+    readonly message: string;
+} | {
+    readonly code: 'REMEMBERED_ROOTS_CORRUPTION';
+    readonly message: string;
+};
+export interface RememberedRootRecordV2 {
+    readonly path: string;
+    readonly addedAtMs: number;
+    readonly lastSeenAtMs: number;
+    readonly source: 'explicit_workspace_path';
+}
+export interface RememberedRootsStorePortV2 {
+    listRoots(): ResultAsync<readonly string[], RememberedRootsStoreError>;
+    listRootRecords(): ResultAsync<readonly RememberedRootRecordV2[], RememberedRootsStoreError>;
+    rememberRoot(rootPath: string): ResultAsync<void, RememberedRootsStoreError>;
+}

package/dist/v2/ports/remembered-roots-store.port.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.8.2",
+  "version": "3.9.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {