@zaalipro/dsh-workflows 0.1.0-rc.12

package/lib/types/supervisor/storage/run-files.js

@@ -0,0 +1,346 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { BoundedFileError, assertSafeComponent } from './bounded-file.js';
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const decoder = new TextDecoder('utf-8', { fatal: true });
+const encoder = new TextEncoder();
+function checkName(name) {
+    if (!NAME.test(name) || name === '.' || name === '..' || name.includes('/') || name.includes('\\')) {
+        throw new BoundedFileError(`scratch name "${name}" is invalid`, 'WORKFLOW_STORAGE_UNSAFE');
+    }
+    return name;
+}
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+/** Only explicit filesystem absence codes are allowed to become an
+ * `undefined` scratch read.  Message matching is intentionally forbidden:
+ * provider identity/permission failures often contain the words "not found"
+ * and must remain fatal. */
+function isNotFound(error) {
+    const code = errorCode(error);
+    return code === 'ENOENT' || code === 'FS_NOT_FOUND';
+}
+function hasStableIdentity(identity) {
+    if (identity === undefined || !Number.isSafeInteger(Number(identity.size)) || Number(identity.size) < 0)
+        return false;
+    if (identity.nlink !== undefined && identity.nlink !== 1)
+        return false;
+    const posix = Number.isSafeInteger(Number(identity.dev)) && Number.isSafeInteger(Number(identity.ino))
+        && !Number.isNaN(Number(identity.dev)) && !Number.isNaN(Number(identity.ino));
+    return posix || identity.version !== undefined;
+}
+function assertLimits(limits) {
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new RangeError(`${name} must be a positive safe integer`);
+    }
+    if (limits.maxPendingOperations > limits.maxOperations)
+        throw new RangeError('maxPendingOperations must not exceed maxOperations');
+    if (limits.maxFileBytes > limits.maxTotalBytes)
+        throw new RangeError('maxFileBytes must not exceed maxTotalBytes');
+}
+/** Run-scoped scratch authority with operation, pending, file, and byte quotas. */
+export class RunScratchStore {
+    limits;
+    operations = 0;
+    pending = 0;
+    closed = false;
+    initialized = false;
+    files = new Map();
+    total = 0;
+    tail = Promise.resolve();
+    inflight = new Set();
+    lifetime = new AbortController();
+    directory;
+    path;
+    constructor(directoryOrPath, limits) {
+        this.limits = limits;
+        assertLimits(limits);
+        if (typeof directoryOrPath === 'string')
+            this.path = directoryOrPath;
+        else {
+            this.directory = directoryOrPath;
+            this.path = directoryOrPath.path;
+        }
+    }
+    signal(signal) {
+        return signal === undefined ? this.lifetime.signal : AbortSignal.any([signal, this.lifetime.signal]);
+    }
+    /** Wait for a fixed point.  A single snapshot of `inflight` is not enough:
+     * a queued write can settle the same turn that a read's finally-handler is
+     * removing itself.  Rechecking the tail, set, and counter prevents list or
+     * disposal from inventorying/closing while an admitted operation is still
+     * capable of touching scratch. */
+    async drain() {
+        for (;;) {
+            const tail = this.tail;
+            const inflight = [...this.inflight];
+            await Promise.allSettled([tail, ...inflight]);
+            if (tail === this.tail && this.inflight.size === 0 && this.pending === 0)
+                return;
+        }
+    }
+    begin(name, supplied) {
+        if (this.closed)
+            throw new BoundedFileError('scratch store is disposed');
+        checkName(name);
+        const signal = this.signal(supplied);
+        signal.throwIfAborted();
+        if (this.operations >= this.limits.maxOperations)
+            throw new BoundedFileError('scratch operation quota exceeded', 'WORKFLOW_STORAGE_LIMIT');
+        if (this.pending >= this.limits.maxPendingOperations)
+            throw new BoundedFileError('scratch pending-operation quota exceeded', 'WORKFLOW_STORAGE_LIMIT');
+        this.operations += 1;
+        this.pending += 1;
+        return signal;
+    }
+    track(operation) {
+        this.inflight.add(operation);
+        void operation.finally(() => { this.inflight.delete(operation); this.pending -= 1; }).catch(() => undefined);
+        return operation;
+    }
+    async ensureDirectory(signal) {
+        signal.throwIfAborted();
+        if (this.directory !== undefined) {
+            await this.directory.assertIdentity(signal);
+            return this.directory;
+        }
+        await mkdir(this.path, { recursive: true, mode: 0o700 });
+        return undefined;
+    }
+    async inventory(signal) {
+        if (this.initialized)
+            return;
+        const directory = await this.ensureDirectory(signal);
+        const entries = directory?.listEntries !== undefined
+            ? await directory.listEntries(signal)
+            : (await readdir(this.path)).sort().map(name => ({ name, type: 'file' }));
+        if (entries.length > this.limits.maxFiles)
+            throw new BoundedFileError('scratch file quota exceeded', 'WORKFLOW_STORAGE_LIMIT');
+        let total = 0;
+        for (const entry of entries) {
+            const name = entry.name;
+            checkName(name);
+            if (entry.type !== 'file' || entry.identity?.nlink !== undefined && entry.identity.nlink !== 1) {
+                throw new BoundedFileError(`workflow storage path "${join(this.path, name)}" is unsafe: scratch entry is not a regular file`, 'WORKFLOW_STORAGE_UNSAFE');
+            }
+            let identity = entry.identity;
+            if (identity === undefined && directory !== undefined) {
+                if (directory.fileInfo === undefined)
+                    throw new BoundedFileError('descriptor-rooted scratch metadata is unavailable', 'WORKFLOW_STORAGE_UNSUPPORTED');
+                identity = await directory.fileInfo(name, signal);
+            }
+            if (directory !== undefined && !hasStableIdentity(identity)) {
+                throw new BoundedFileError(`descriptor-rooted scratch metadata for "${name}" is unavailable`, 'WORKFLOW_STORAGE_UNSUPPORTED');
+            }
+            const size = identity?.size ?? (await lstat(join(this.path, name))).size;
+            if (!Number.isSafeInteger(Number(size)) || Number(size) < 0)
+                throw new BoundedFileError('scratch file metadata is invalid', 'WORKFLOW_STORAGE_UNSUPPORTED');
+            if (size > this.limits.maxFileBytes)
+                throw new BoundedFileError('scratch file exceeds per-file quota', 'WORKFLOW_STORAGE_LIMIT');
+            total += size;
+            if (total > this.limits.maxTotalBytes)
+                throw new BoundedFileError('scratch total quota exceeded', 'WORKFLOW_STORAGE_LIMIT');
+            this.files.set(name, size);
+        }
+        this.total = total;
+        this.initialized = true;
+    }
+    async read(name, supplied) {
+        const signal = this.begin(name, supplied);
+        const operation = (async () => {
+            await this.inventory(signal);
+            const directory = await this.ensureDirectory(signal);
+            try {
+                let bytes;
+                if (directory !== undefined)
+                    bytes = await directory.readBytes(name, signal, this.limits.maxFileBytes);
+                else {
+                    if (process.platform === 'win32' || !constants.O_NOFOLLOW)
+                        throw new BoundedFileError(`safe workflow storage is unavailable on ${process.platform}`, 'WORKFLOW_STORAGE_UNSUPPORTED');
+                    const handle = await open(join(this.path, name), constants.O_RDONLY | constants.O_NOFOLLOW);
+                    try {
+                        const info = await handle.stat();
+                        if (!info.isFile() || info.nlink !== 1 || info.size > this.limits.maxFileBytes)
+                            throw new BoundedFileError('scratch file is unsafe or oversized', 'WORKFLOW_STORAGE_UNSAFE');
+                        bytes = new Uint8Array(await handle.readFile());
+                    }
+                    finally {
+                        await handle.close();
+                    }
+                }
+                signal.throwIfAborted();
+                return decoder.decode(bytes);
+            }
+            catch (error) {
+                if (isNotFound(error))
+                    return undefined;
+                throw error;
+            }
+        })();
+        return this.track(operation);
+    }
+    async write(name, content, supplied) {
+        const signal = this.begin(name, supplied);
+        const operation = this.tail.then(async () => {
+            await this.inventory(signal);
+            const bytes = encoder.encode(content);
+            if (bytes.byteLength > this.limits.maxFileBytes)
+                throw new BoundedFileError('scratch file exceeds per-file quota', 'WORKFLOW_STORAGE_LIMIT');
+            const previous = this.files.get(name) ?? 0;
+            if (!this.files.has(name) && this.files.size >= this.limits.maxFiles)
+                throw new BoundedFileError('scratch file quota exceeded', 'WORKFLOW_STORAGE_LIMIT');
+            const nextTotal = this.total - previous + bytes.byteLength;
+            if (nextTotal > this.limits.maxTotalBytes)
+                throw new BoundedFileError('scratch total quota exceeded', 'WORKFLOW_STORAGE_LIMIT');
+            const directory = await this.ensureDirectory(signal);
+            if (directory === undefined)
+                throw new BoundedFileError('descriptor-rooted scratch publication is unavailable', 'WORKFLOW_STORAGE_UNSUPPORTED');
+            let expected;
+            if (this.files.has(name)) {
+                let info;
+                if (directory.fileInfo !== undefined)
+                    info = await directory.fileInfo(name, signal);
+                else
+                    throw new BoundedFileError('descriptor-rooted scratch metadata is unavailable', 'WORKFLOW_STORAGE_UNSUPPORTED');
+                if (!hasStableIdentity(info))
+                    throw new BoundedFileError('scratch destination changed', 'WORKFLOW_STORAGE_UNSAFE');
+                expected = { kind: 'replaceIfVersion', version: info };
+            }
+            else
+                expected = { kind: 'createIfAbsent' };
+            await directory.writeText(name, content, expected, signal);
+            await directory.assertIdentity(signal);
+            this.files.set(name, bytes.byteLength);
+            this.total = nextTotal;
+        });
+        this.tail = operation.catch(() => undefined);
+        return this.track(operation);
+    }
+    async list(supplied) {
+        if (this.closed)
+            throw new BoundedFileError('scratch store is disposed');
+        const signal = this.signal(supplied);
+        supplied?.throwIfAborted();
+        await this.drain();
+        await this.inventory(signal);
+        signal.throwIfAborted();
+        return [...this.files.keys()].sort();
+    }
+    cancel(reason = new Error('scratch operation cancelled')) {
+        if (!this.lifetime.signal.aborted)
+            this.lifetime.abort(reason);
+    }
+    async dispose() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.cancel(new Error('scratch store disposed'));
+        await this.drain();
+        let first;
+        try {
+            await this.directory?.close();
+        }
+        catch (error) {
+            first = error;
+        }
+        this.directory = undefined;
+        if (first !== undefined)
+            throw first;
+    }
+}
+/** Own the run-directory parent for as long as a scratch capability is live.
+ * A child PrivateDirectory retains its parent descriptor, but the parent must
+ * also receive the caller's close request so its descriptor is eventually
+ * released after the child drains. */
+class RetainedScratchStore {
+    inner;
+    parent;
+    disposed = false;
+    constructor(inner, parent) {
+        this.inner = inner;
+        this.parent = parent;
+    }
+    read(name, signal) { return this.inner.read(name, signal); }
+    write(name, content, signal) { return this.inner.write(name, content, signal); }
+    list(signal) { return this.inner.list(signal); }
+    cancel(reason) { this.inner.cancel?.(reason); }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        let first;
+        try {
+            await this.inner.dispose();
+        }
+        catch (error) {
+            first = error;
+        }
+        try {
+            await this.parent.close();
+        }
+        catch (error) {
+            first ??= error;
+        }
+        if (first !== undefined)
+            throw first;
+    }
+}
+/** Open the scratch component of one already-published run directory. */
+export async function openRunScratch(layout, runDirectory, limits) {
+    assertSafeComponent(runDirectory, 'run directory');
+    await layout.lease.assertCurrent();
+    const run = await layout.runs.openDirectory(runDirectory);
+    let transferred = false;
+    try {
+        const scratch = await run.openDirectory('scratch');
+        const result = new RetainedScratchStore(new RunScratchStore(scratch, limits), run);
+        transferred = true;
+        return result;
+    }
+    finally {
+        if (!transferred)
+            await run.close();
+    }
+}
+/** Create an immutable projection and descriptor-rooted run scratch authority. */
+export async function createRunFiles(layout, runDirectory, scriptBytes, limits) {
+    assertSafeComponent(runDirectory, 'run directory');
+    const maxScriptBytes = limits.maxScriptBytes ?? 1_048_576;
+    if (scriptBytes.byteLength > maxScriptBytes)
+        throw new BoundedFileError('workflow script exceeds configured limit', 'WORKFLOW_STORAGE_LIMIT');
+    await layout.lease.assertCurrent();
+    const run = await layout.runs.openDirectory(runDirectory, undefined, { create: true });
+    let transferred = false;
+    try {
+        await run.writeText('script.js', decoder.decode(scriptBytes), { kind: 'createIfAbsent' });
+        const scratchDirectory = await run.openDirectory('scratch', undefined, { create: true });
+        const details = await run.openDirectory('details', undefined, { create: true });
+        await details.close();
+        const scratch = new RetainedScratchStore(new RunScratchStore(scratchDirectory, limits), run);
+        transferred = true;
+        let disposed = false;
+        return {
+            runDirectory,
+            scriptPath: join(layout.runs.path, runDirectory, 'script.js'),
+            script: new Uint8Array(scriptBytes),
+            scratch,
+            detailsPath: join(layout.runs.path, runDirectory, 'details'),
+            async dispose() { if (disposed)
+                return; disposed = true; await scratch.dispose(); },
+        };
+    }
+    finally {
+        if (!transferred)
+            await run.close();
+    }
+}
+/** Derive a run directory from an exposed script projection without leaking it to the engine. */
+export function scratchDirectoryFromScriptPath(scriptPath) {
+    return dirname(scriptPath);
+}
+//# sourceMappingURL=run-files.js.map

package/lib/types/supervisor/storage/run-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-files.js","sourceRoot":"","sources":["../../../../src/supervisor/storage/run-files.ts"],"names":[],"mappings":"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"}

package/lib/types/supervisor/types.d.ts

@@ -0,0 +1,295 @@
+import type { JsonValue, WorkflowRunStatus, WorkflowRunOutcomeState } from './storage/manifest-types.js';
+import type { WorkflowScope } from '../registry/types.js';
+export type { WorkflowRunStatus, WorkflowRunOutcomeState };
+/** Plain string on the wire: Typert strict codecs reject TypeScript `__brand` intersections. */
+export type SupervisedWorkflowRunId = string;
+export type WorkflowMemberId = string;
+export type WorkflowGateId = string;
+export type WorkflowRunCursor = string;
+export type WorkflowRunFeedEpoch = string;
+export interface WorkflowPhase {
+    readonly title: string;
+    readonly detail?: string;
+    readonly provider?: string;
+    readonly model?: string;
+}
+export interface WorkflowGateInfo {
+    readonly id?: WorkflowGateId;
+    readonly kind: 'user' | 'back_off' | 'no_progress' | 'verification' | 'infra';
+    readonly message: string;
+    readonly resumable: boolean;
+}
+export interface SupervisedWorkflowRunInfo {
+    readonly id: SupervisedWorkflowRunId;
+    readonly displayName: string;
+    readonly name: string;
+}
+export type SupervisedWorkflowStopReason = 'completed' | 'cancelled' | 'error' | 'interrupted';
+export interface SupervisedWorkflowResultInfo {
+    readonly stopReason: SupervisedWorkflowStopReason;
+    readonly error?: string;
+    readonly agentsStarted: number;
+}
+export interface SupervisedWorkflowMemberLifecycleInfo {
+    readonly memberId: WorkflowMemberId;
+    readonly seq: number;
+    readonly label: string;
+    readonly phase?: string;
+    readonly childSessionId: string;
+    readonly status: 'running' | 'completed' | 'failed' | 'cancelled';
+}
+export interface WorkflowGateRequest {
+    readonly info: SupervisedWorkflowRunInfo;
+    readonly executionId: string;
+    readonly gateId: WorkflowGateId;
+    readonly gate: WorkflowGateInfo;
+    readonly parent: unknown;
+    readonly signal: AbortSignal;
+}
+export interface WorkflowRunRecordingSnapshot {
+    readonly info: SupervisedWorkflowRunInfo;
+    readonly run: WorkflowRunHead;
+    readonly members: readonly SupervisedWorkflowMemberLifecycleInfo[];
+    readonly result?: SupervisedWorkflowResultInfo;
+}
+export interface WorkflowRunMemberCounts {
+    readonly total: number;
+    readonly running: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly cancelled: number;
+}
+export type WorkflowRunAction = 'pause' | 'resume' | 'stop' | 'save';
+export interface WorkflowRunTerminalSummary {
+    readonly stopReason: 'completed' | 'cancelled' | 'error' | 'interrupted';
+    readonly resultState: Exclude<WorkflowRunOutcomeState, 'pending'>;
+    readonly preview?: string;
+    readonly error?: string;
+}
+export interface WorkflowRunHead {
+    readonly runId: SupervisedWorkflowRunId;
+    readonly displayName: string;
+    readonly name: string;
+    readonly description: string;
+    readonly status: WorkflowRunStatus;
+    readonly phase?: string;
+    readonly budget: {
+        readonly total: number;
+        readonly spent: number;
+        readonly remaining: number;
+    };
+    readonly memberCounts: WorkflowRunMemberCounts;
+    readonly startedAt: number;
+    readonly settledAt?: number;
+    readonly terminal?: WorkflowRunTerminalSummary;
+    readonly allowedActions: readonly WorkflowRunAction[];
+    readonly revision: number;
+    readonly detailRevision: number;
+    readonly membersRevision: number;
+    readonly logsRevision: number;
+    readonly resultRevision: number;
+    readonly artifactsRevision: number;
+}
+export interface WorkflowRunListRequest {
+    readonly cursor?: WorkflowRunCursor;
+    readonly limit?: number;
+}
+export interface WorkflowRunListPage {
+    readonly epoch: WorkflowRunFeedEpoch;
+    readonly sessionRevision: number;
+    readonly items: readonly WorkflowRunHead[];
+    readonly nextCursor?: WorkflowRunCursor;
+    readonly total: number;
+}
+export interface WorkflowRunRequest {
+    readonly runId: SupervisedWorkflowRunId;
+}
+export interface WorkflowRunDetail {
+    readonly run: WorkflowRunHead;
+    readonly phases?: readonly WorkflowPhase[];
+    readonly gate?: WorkflowGateInfo;
+    readonly error?: string;
+    readonly scriptPath?: string;
+}
+export interface WorkflowRunMemberHead {
+    readonly memberId: WorkflowMemberId;
+    readonly seq: number;
+    readonly label: string;
+    readonly phase?: string;
+    readonly status: 'running' | 'completed' | 'failed' | 'cancelled';
+    readonly startedAt?: number;
+    readonly settledAt?: number;
+    readonly outcome: WorkflowRunOutcomeState;
+    readonly childSessionId?: string;
+}
+export interface WorkflowRunMemberPage {
+    readonly items: readonly WorkflowRunMemberHead[];
+    readonly nextCursor?: WorkflowRunCursor;
+    readonly total: number;
+    readonly revision: number;
+}
+export interface WorkflowRunMembersRequest extends WorkflowRunRequest {
+    readonly cursor?: WorkflowRunCursor;
+    readonly limit?: number;
+}
+export type WorkflowRunValueView = {
+    readonly state: 'pending' | 'not-produced' | 'evicted';
+} | {
+    readonly state: 'available';
+    readonly content: {
+        readonly kind: 'value';
+        readonly value: JsonValue;
+    } | {
+        readonly kind: 'preview';
+        readonly text: string;
+    };
+    readonly totalBytes: number;
+    readonly truncated: boolean;
+};
+export interface WorkflowRunMemberDetail {
+    readonly member: WorkflowRunMemberHead;
+    readonly childSessionId?: string;
+    readonly outcome: WorkflowRunValueView;
+}
+export interface WorkflowRunMemberRequest extends WorkflowRunRequest {
+    readonly memberId: WorkflowMemberId;
+}
+export interface WorkflowRunLogLine {
+    readonly index: number;
+    readonly text: string;
+}
+export interface WorkflowRunLogPage {
+    readonly items: readonly WorkflowRunLogLine[];
+    readonly nextCursor?: WorkflowRunCursor;
+    readonly evicted: number;
+    readonly total: number;
+    readonly revision: number;
+}
+export interface WorkflowRunLogsRequest extends WorkflowRunRequest {
+    readonly cursor?: WorkflowRunCursor;
+    readonly limit?: number;
+}
+export interface WorkflowRunResultView {
+    readonly value: WorkflowRunValueView;
+    readonly error?: string;
+    readonly revision: number;
+}
+export interface WorkflowRunArtifactView {
+    readonly name: string;
+    readonly bytes: number;
+}
+export interface WorkflowRunArtifactChunk {
+    readonly artifact: WorkflowRunArtifactView;
+    readonly text: string;
+    readonly offsetBytes: number;
+    readonly returnedBytes: number;
+    readonly totalBytes: number;
+    readonly revision: number;
+    readonly nextCursor?: WorkflowRunCursor;
+}
+export interface WorkflowRunArtifactPage {
+    readonly items: readonly WorkflowRunArtifactView[];
+    readonly nextCursor?: WorkflowRunCursor;
+    readonly omitted: number;
+    readonly total: number;
+    readonly revision: number;
+}
+export interface WorkflowRunArtifactsRequest extends WorkflowRunRequest {
+    readonly cursor?: WorkflowRunCursor;
+    readonly limit?: number;
+}
+export interface WorkflowRunArtifactRequest extends WorkflowRunRequest {
+    readonly name: string;
+    readonly cursor?: WorkflowRunCursor;
+    readonly maxBytes?: number;
+    readonly expectedRevision?: number;
+}
+export interface WorkflowRunControlRequest extends WorkflowRunRequest {
+    readonly action: WorkflowRunAction;
+    readonly expectedRevision: number;
+}
+export interface WorkflowRunControlResult {
+    readonly run: WorkflowRunHead;
+}
+export type WorkflowRunChange = {
+    readonly kind: 'invalidate-all';
+} | {
+    readonly kind: 'invalidate';
+    readonly sessionId: string;
+    readonly revision: number;
+};
+export type WorkflowRemoteFailureCode = 'invalid-page-limit' | 'invalid-artifact-limit' | 'invalid-cursor' | 'stale-cursor' | 'workspace-unavailable' | 'definition-invalid' | 'run-not-found' | 'member-not-found' | 'artifact-not-found' | 'artifact-changed' | 'revision-conflict' | 'action-unavailable' | 'storage-unavailable';
+export type WorkflowRemoteFailure = {
+    readonly code: Exclude<WorkflowRemoteFailureCode, 'revision-conflict' | 'action-unavailable'>;
+    readonly message: string;
+    readonly details?: {
+        readonly min?: number;
+        readonly max?: number;
+        readonly revision?: number;
+    };
+} | {
+    readonly code: 'revision-conflict';
+    readonly message: 'workflow run changed; refresh it before applying a control';
+    readonly details: {
+        readonly run: WorkflowRunHead;
+    };
+} | {
+    readonly code: 'action-unavailable';
+    readonly message: string;
+    readonly details: {
+        readonly reason: 'budget-limited' | 'invalid-state' | 'save-ineligible';
+        readonly run?: WorkflowRunHead;
+    };
+};
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        'workflows/run-start'(info: SupervisedWorkflowRunInfo): void;
+        'workflows/member-start'(info: SupervisedWorkflowRunInfo, member: SupervisedWorkflowMemberLifecycleInfo): void;
+        'workflows/member-end'(info: SupervisedWorkflowRunInfo, member: SupervisedWorkflowMemberLifecycleInfo): void;
+        'workflows/run-end'(info: SupervisedWorkflowRunInfo, result: SupervisedWorkflowResultInfo): void;
+        'workflows/gate-request'(request: WorkflowGateRequest): void;
+        /**
+         * Invalidation-only workflow run hint. Never carries a run head.
+         * @mode emit
+         */
+        'workflows/run-change'(change: WorkflowRunChange): void;
+    }
+}
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface TypertRemoteEventSelection {
+        'workflows/run-change': true;
+    }
+}
+export type WorkflowRemoteResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: WorkflowRemoteFailure;
+};
+export interface WorkflowLaunched {
+    readonly displayName: string;
+    readonly runId: SupervisedWorkflowRunId;
+    readonly scriptPath?: string;
+    readonly status: 'started';
+}
+/** Success coverage sentence required by 6.5 / SH8; never a live-tool claim. */
+export declare const VALIDATION_NOTE = "Validated one args-selected path with canned agent results; other branches, live tools, and live schema responses were not covered.";
+export type WorkflowValidation = {
+    readonly ok: true;
+    readonly status: 'completed';
+    readonly value: JsonValue;
+    readonly note: typeof VALIDATION_NOTE;
+} | {
+    readonly ok: true;
+    readonly status: 'would-pause';
+    readonly value: string;
+    readonly note: typeof VALIDATION_NOTE;
+} | {
+    readonly ok: false;
+    readonly status: 'error';
+    readonly error: string;
+    readonly errorCode?: string;
+};
+export type WorkflowSaveScope = Extract<WorkflowScope, 'project' | 'user'>;
+//# sourceMappingURL=types.d.ts.map