@exaudeus/workrail 3.12.0 → 3.13.0

package/dist/mcp/v2/tool-registry.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildV2ToolRegistry = buildV2ToolRegistry;
 const handler_factory_js_1 = require("../handler-factory.js");
 const tools_js_1 = require("./tools.js");
+const v2_manage_workflow_source_js_1 = require("../handlers/v2-manage-workflow-source.js");
 const v2_execution_js_1 = require("../handlers/v2-execution.js");
 const v2_workflow_js_1 = require("../handlers/v2-workflow.js");
 const v2_checkpoint_js_1 = require("../handlers/v2-checkpoint.js");
@@ -46,6 +47,12 @@ function buildV2ToolRegistry(buildTool) {
             inputSchema: tools_js_1.V2ResumeSessionInput,
             annotations: tools_js_1.V2_TOOL_ANNOTATIONS.resume_session,
         }),
+        buildTool({
+            name: 'manage_workflow_source',
+            title: tools_js_1.V2_TOOL_TITLES.manage_workflow_source,
+            inputSchema: tools_js_1.V2ManageWorkflowSourceInput,
+            annotations: tools_js_1.V2_TOOL_ANNOTATIONS.manage_workflow_source,
+        }),
     ];
     const handlers = {
         list_workflows: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ListWorkflowsInput, v2_workflow_js_1.handleV2ListWorkflows),
@@ -54,6 +61,7 @@ function buildV2ToolRegistry(buildTool) {
         continue_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ContinueWorkflowInput, v2_execution_js_1.handleV2ContinueWorkflow, tools_js_1.V2ContinueWorkflowInputShape, workflow_protocol_contracts_js_1.CONTINUE_WORKFLOW_PROTOCOL.aliasMap),
         checkpoint_workflow: (0, handler_factory_js_1.createHandler)(tools_js_1.V2CheckpointWorkflowInput, v2_checkpoint_js_1.handleV2CheckpointWorkflow),
         resume_session: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ResumeSessionInput, v2_resume_js_1.handleV2ResumeSession),
+        manage_workflow_source: (0, handler_factory_js_1.createHandler)(tools_js_1.V2ManageWorkflowSourceInput, v2_manage_workflow_source_js_1.handleV2ManageWorkflowSource),
     };
     return { tools, handlers };
 }

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

@@ -174,6 +174,17 @@ export declare const V2ResumeSessionInput: z.ZodObject<{
     sameWorkspaceOnly?: boolean | undefined;
 }>;
 export type V2ResumeSessionInput = z.infer<typeof V2ResumeSessionInput>;
+export declare const V2ManageWorkflowSourceInput: z.ZodObject<{
+    action: z.ZodEnum<["attach", "detach"]>;
+    path: z.ZodEffects<z.ZodString, string, string>;
+}, "strict", z.ZodTypeAny, {
+    path: string;
+    action: "attach" | "detach";
+}, {
+    path: string;
+    action: "attach" | "detach";
+}>;
+export type V2ManageWorkflowSourceInput = z.infer<typeof V2ManageWorkflowSourceInput>;
 export declare const V2CheckpointWorkflowInput: z.ZodObject<{
     checkpointToken: z.ZodString;
 }, "strict", z.ZodTypeAny, {
@@ -189,5 +200,6 @@ export declare const V2_TOOL_TITLES: {
     readonly continue_workflow: "Continue Workflow (v2)";
     readonly checkpoint_workflow: "Checkpoint Workflow (v2)";
     readonly resume_session: "Resume Session (v2)";
+    readonly manage_workflow_source: "Manage Workflow Source (v2)";
 };
 export declare const V2_TOOL_ANNOTATIONS: Readonly<Record<keyof typeof V2_TOOL_TITLES, ToolAnnotations>>;

package/dist/mcp/v2/tools.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2CheckpointWorkflowInput = exports.V2ResumeSessionInput = exports.V2ContinueWorkflowInput = exports.V2ContinueWorkflowInputShape = exports.V2StartWorkflowInput = exports.V2InspectWorkflowInput = exports.V2ListWorkflowsInput = void 0;
+exports.V2_TOOL_ANNOTATIONS = exports.V2_TOOL_TITLES = exports.V2CheckpointWorkflowInput = exports.V2ManageWorkflowSourceInput = exports.V2ResumeSessionInput = exports.V2ContinueWorkflowInput = exports.V2ContinueWorkflowInputShape = exports.V2StartWorkflowInput = exports.V2InspectWorkflowInput = exports.V2ListWorkflowsInput = void 0;
 const path_1 = __importDefault(require("path"));
 const zod_1 = require("zod");
 const workflow_protocol_contracts_js_1 = require("../workflow-protocol-contracts.js");
@@ -112,6 +112,10 @@ exports.V2ResumeSessionInput = zod_1.z.object({
     sameWorkspaceOnly: zod_1.z.boolean().optional().describe('If true, only sessions from the same repo/workspace are considered when repo_root_hash is available. ' +
         'Use this when the user clearly means "resume work from this repo only".'),
 }).strict();
+exports.V2ManageWorkflowSourceInput = zod_1.z.object({
+    action: zod_1.z.enum(['attach', 'detach']).describe('The operation to perform. "attach" registers the directory as a managed workflow source; "detach" removes it. Both operations are idempotent.'),
+    path: zod_1.z.string().min(1).refine((p) => path_1.default.isAbsolute(p), 'path must be an absolute path').describe('Absolute filesystem path to the workflow directory to attach or detach. Must be an absolute path. The path is normalized (resolved) before storage.'),
+}).strict();
 exports.V2CheckpointWorkflowInput = zod_1.z.object({
     checkpointToken: zod_1.z.string().min(1).describe('The checkpoint token from the most recent start_workflow or continue_workflow response. ' +
         'Creates a checkpoint on the current step without advancing. Idempotent — calling with the same token is safe.'),
@@ -123,6 +127,7 @@ exports.V2_TOOL_TITLES = {
     continue_workflow: 'Continue Workflow (v2)',
     checkpoint_workflow: 'Checkpoint Workflow (v2)',
     resume_session: 'Resume Session (v2)',
+    manage_workflow_source: 'Manage Workflow Source (v2)',
 };
 exports.V2_TOOL_ANNOTATIONS = {
     list_workflows: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
@@ -131,4 +136,5 @@ exports.V2_TOOL_ANNOTATIONS = {
     continue_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
     checkpoint_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
     resume_session: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    manage_workflow_source: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };

package/dist/v2/infra/in-memory/managed-source-store/index.d.ts

@@ -0,0 +1,8 @@
+import type { ResultAsync } from 'neverthrow';
+import type { ManagedSourceRecordV2, ManagedSourceStoreError, ManagedSourceStorePortV2 } from '../../../ports/managed-source-store.port.js';
+export declare class InMemoryManagedSourceStoreV2 implements ManagedSourceStorePortV2 {
+    private readonly sources;
+    list(): ResultAsync<readonly ManagedSourceRecordV2[], ManagedSourceStoreError>;
+    attach(sourcePath: string): ResultAsync<void, ManagedSourceStoreError>;
+    detach(sourcePath: string): ResultAsync<void, ManagedSourceStoreError>;
+}

package/dist/v2/infra/in-memory/managed-source-store/index.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InMemoryManagedSourceStoreV2 = void 0;
+const path_1 = __importDefault(require("path"));
+const neverthrow_1 = require("neverthrow");
+class InMemoryManagedSourceStoreV2 {
+    constructor() {
+        this.sources = [];
+    }
+    list() {
+        return (0, neverthrow_1.okAsync)([...this.sources]);
+    }
+    attach(sourcePath) {
+        const normalizedPath = path_1.default.resolve(sourcePath);
+        const alreadyPresent = this.sources.some((s) => s.path === normalizedPath);
+        if (!alreadyPresent) {
+            this.sources.push({ path: normalizedPath, addedAtMs: Date.now() });
+        }
+        return (0, neverthrow_1.okAsync)(undefined);
+    }
+    detach(sourcePath) {
+        const normalizedPath = path_1.default.resolve(sourcePath);
+        const index = this.sources.findIndex((s) => s.path === normalizedPath);
+        if (index !== -1) {
+            this.sources.splice(index, 1);
+        }
+        return (0, neverthrow_1.okAsync)(undefined);
+    }
+}
+exports.InMemoryManagedSourceStoreV2 = InMemoryManagedSourceStoreV2;

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

@@ -19,4 +19,6 @@ export declare class LocalDataDirV2 implements DataDirPortV2 {
     sessionManifestPath(sessionId: SessionId): string;
     sessionLockPath(sessionId: SessionId): string;
     tokenIndexPath(): string;
+    managedSourcesPath(): string;
+    managedSourcesLockPath(): string;
 }

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

@@ -89,5 +89,11 @@ class LocalDataDirV2 {
     tokenIndexPath() {
         return path.join(this.keysDir(), 'token-index.jsonl');
     }
+    managedSourcesPath() {
+        return path.join(this.root(), 'managed-sources', 'managed-sources.json');
+    }
+    managedSourcesLockPath() {
+        return path.join(this.root(), 'managed-sources', 'managed-sources.lock');
+    }
 }
 exports.LocalDataDirV2 = LocalDataDirV2;

package/dist/v2/infra/local/managed-source-store/index.d.ts

@@ -0,0 +1,15 @@
+import type { ResultAsync } from 'neverthrow';
+import type { DataDirPortV2 } from '../../../ports/data-dir.port.js';
+import type { FileSystemPortV2 } from '../../../ports/fs.port.js';
+import type { ManagedSourceRecordV2, ManagedSourceStoreError, ManagedSourceStorePortV2 } from '../../../ports/managed-source-store.port.js';
+export declare class LocalManagedSourceStoreV2 implements ManagedSourceStorePortV2 {
+    private readonly dataDir;
+    private readonly fs;
+    constructor(dataDir: DataDirPortV2, fs: FileSystemPortV2);
+    list(): ResultAsync<readonly ManagedSourceRecordV2[], ManagedSourceStoreError>;
+    attach(sourcePath: string): ResultAsync<void, ManagedSourceStoreError>;
+    detach(sourcePath: string): ResultAsync<void, ManagedSourceStoreError>;
+    private readSources;
+    private persist;
+    private withLock;
+}

package/dist/v2/infra/local/managed-source-store/index.js

@@ -0,0 +1,164 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalManagedSourceStoreV2 = void 0;
+const path_1 = __importDefault(require("path"));
+const zod_1 = require("zod");
+const neverthrow_1 = require("neverthrow");
+const MANAGED_SOURCE_LOCK_RETRY_MS = 250;
+const jcs_js_1 = require("../../../durable-core/canonical/jcs.js");
+const ManagedSourceRecordSchema = zod_1.z.object({
+    path: zod_1.z.string(),
+    addedAtMs: zod_1.z.number().int().nonnegative(),
+});
+const ManagedSourcesFileSchema = zod_1.z.object({
+    v: zod_1.z.literal(1),
+    sources: zod_1.z.array(ManagedSourceRecordSchema),
+});
+function mapFsToManagedSourceError(e) {
+    if (e.code === 'FS_ALREADY_EXISTS') {
+        return {
+            code: 'MANAGED_SOURCE_BUSY',
+            message: 'Managed sources are being updated by another WorkRail process.',
+            retry: { kind: 'retryable_after_ms', afterMs: MANAGED_SOURCE_LOCK_RETRY_MS },
+            lockPath: 'managed-sources.lock',
+        };
+    }
+    return { code: 'MANAGED_SOURCE_IO_ERROR', message: e.message };
+}
+function normalizeRecords(sources) {
+    const seen = new Set();
+    const normalized = [];
+    for (const source of sources) {
+        const normalizedPath = path_1.default.resolve(source.path);
+        if (seen.has(normalizedPath))
+            continue;
+        seen.add(normalizedPath);
+        normalized.push({ path: normalizedPath, addedAtMs: source.addedAtMs });
+    }
+    return normalized;
+}
+class LocalManagedSourceStoreV2 {
+    constructor(dataDir, fs) {
+        this.dataDir = dataDir;
+        this.fs = fs;
+    }
+    list() {
+        return this.readSources();
+    }
+    attach(sourcePath) {
+        const normalizedPath = path_1.default.resolve(sourcePath);
+        const nowMs = Date.now();
+        return this.withLock(() => this.readSources().andThen((sources) => {
+            const alreadyPresent = sources.some((s) => s.path === normalizedPath);
+            if (alreadyPresent)
+                return (0, neverthrow_1.okAsync)(undefined);
+            const next = [...sources, { path: normalizedPath, addedAtMs: nowMs }];
+            return this.persist(next);
+        }));
+    }
+    detach(sourcePath) {
+        const normalizedPath = path_1.default.resolve(sourcePath);
+        return this.withLock(() => this.readSources().andThen((sources) => {
+            const next = sources.filter((s) => s.path !== normalizedPath);
+            if (next.length === sources.length)
+                return (0, neverthrow_1.okAsync)(undefined);
+            return this.persist(next);
+        }));
+    }
+    readSources() {
+        const filePath = this.dataDir.managedSourcesPath();
+        return this.fs.readFileUtf8(filePath)
+            .orElse((e) => {
+            if (e.code === 'FS_NOT_FOUND')
+                return (0, neverthrow_1.okAsync)('');
+            return (0, neverthrow_1.errAsync)(mapFsToManagedSourceError(e));
+        })
+            .andThen((raw) => {
+            if (raw === '')
+                return (0, neverthrow_1.okAsync)([]);
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return (0, neverthrow_1.errAsync)({
+                    code: 'MANAGED_SOURCE_CORRUPTION',
+                    message: `Invalid JSON in managed sources file: ${filePath}`,
+                });
+            }
+            const validated = ManagedSourcesFileSchema.safeParse(parsed);
+            if (!validated.success) {
+                return (0, neverthrow_1.errAsync)({
+                    code: 'MANAGED_SOURCE_CORRUPTION',
+                    message: `Managed sources file has invalid shape: ${filePath}`,
+                });
+            }
+            return (0, neverthrow_1.okAsync)(normalizeRecords(validated.data.sources));
+        });
+    }
+    persist(sources) {
+        const filePath = this.dataDir.managedSourcesPath();
+        const dir = path_1.default.dirname(filePath);
+        const tmpPath = `${filePath}.tmp`;
+        const fileValue = {
+            v: 1,
+            sources: [...normalizeRecords(sources)],
+        };
+        const canonical = (0, jcs_js_1.toCanonicalBytes)(fileValue).mapErr((e) => ({
+            code: 'MANAGED_SOURCE_IO_ERROR',
+            message: `Failed to canonicalize managed sources state: ${e.message}`,
+        }));
+        if (canonical.isErr())
+            return (0, neverthrow_1.errAsync)(canonical.error);
+        const bytes = canonical.value;
+        return this.fs.mkdirp(dir)
+            .mapErr(mapFsToManagedSourceError)
+            .andThen(() => this.fs.openWriteTruncate(tmpPath).mapErr(mapFsToManagedSourceError))
+            .andThen(({ fd }) => this.fs.writeAll(fd, bytes)
+            .mapErr(mapFsToManagedSourceError)
+            .andThen(() => this.fs.fsyncFile(fd).mapErr(mapFsToManagedSourceError))
+            .andThen(() => this.fs.closeFile(fd).mapErr(mapFsToManagedSourceError))
+            .orElse((e) => this.fs.closeFile(fd)
+            .mapErr(() => e)
+            .andThen(() => (0, neverthrow_1.errAsync)(e))))
+            .andThen(() => this.fs.rename(tmpPath, filePath).mapErr(mapFsToManagedSourceError))
+            .andThen(() => this.fs.fsyncDir(dir).mapErr(mapFsToManagedSourceError));
+    }
+    withLock(run) {
+        const lockPath = this.dataDir.managedSourcesLockPath();
+        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(mapFsToManagedSourceError)
+            .andThen(() => this.fs.openExclusive(lockPath, lockBytes)
+            .mapErr((e) => {
+            const mapped = mapFsToManagedSourceError(e);
+            if (mapped.code === 'MANAGED_SOURCE_BUSY') {
+                return { ...mapped, lockPath };
+            }
+            return mapped;
+        }))
+            .andThen(({ fd }) => this.fs.fsyncFile(fd)
+            .mapErr(mapFsToManagedSourceError)
+            .andThen(() => this.fs.closeFile(fd).mapErr(mapFsToManagedSourceError))
+            .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)(mapFsToManagedSourceError(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)(mapFsToManagedSourceError(e));
+        })
+            .andThen(() => (0, neverthrow_1.errAsync)(error))));
+    }
+}
+exports.LocalManagedSourceStoreV2 = LocalManagedSourceStoreV2;

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

@@ -14,4 +14,6 @@ export interface DataDirPortV2 {
     sessionManifestPath(sessionId: SessionId): string;
     sessionLockPath(sessionId: SessionId): string;
     tokenIndexPath(): string;
+    managedSourcesPath(): string;
+    managedSourcesLockPath(): string;
 }

package/dist/v2/ports/managed-source-store.port.d.ts

@@ -0,0 +1,25 @@
+import type { ResultAsync } from 'neverthrow';
+export type ManagedSourceStoreError = {
+    readonly code: 'MANAGED_SOURCE_BUSY';
+    readonly message: string;
+    readonly retry: {
+        readonly kind: 'retryable_after_ms';
+        readonly afterMs: number;
+    };
+    readonly lockPath: string;
+} | {
+    readonly code: 'MANAGED_SOURCE_IO_ERROR';
+    readonly message: string;
+} | {
+    readonly code: 'MANAGED_SOURCE_CORRUPTION';
+    readonly message: string;
+};
+export interface ManagedSourceRecordV2 {
+    readonly path: string;
+    readonly addedAtMs: number;
+}
+export interface ManagedSourceStorePortV2 {
+    list(): ResultAsync<readonly ManagedSourceRecordV2[], ManagedSourceStoreError>;
+    attach(path: string): ResultAsync<void, ManagedSourceStoreError>;
+    detach(path: string): ResultAsync<void, ManagedSourceStoreError>;
+}

package/dist/v2/ports/managed-source-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.12.0",
+  "version": "3.13.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {