@plateforme-ai/lobster 2026.6.12

package/dist/src/sdk/Lobster.js

@@ -0,0 +1,402 @@
+import { randomUUID } from "node:crypto";
+import { runPipelineInternal } from "./runtime.js";
+import { encodeToken, decodeToken } from "./token.js";
+import { compileCached } from "../validation.js";
+import { validateCommandInputState } from "../input_request.js";
+import { deleteStateJson, readStateJson, writeStateJson } from "../state/store.js";
+/**
+ * @typedef {Object} LobsterResult
+ * @property {boolean} ok - Whether the workflow completed successfully
+ * @property {'ok' | 'needs_approval' | 'needs_input' | 'cancelled' | 'error'} status - Workflow status
+ * @property {any[]} output - Output items from the workflow
+ * @property {Object|null} requiresApproval - Approval request if halted
+ * @property {string} [requiresApproval.prompt] - Approval prompt
+ * @property {any[]} [requiresApproval.items] - Items pending approval
+ * @property {string} [requiresApproval.resumeToken] - Token to resume workflow
+ * @property {Object|null} requiresInput - Input request if halted
+ * @property {string} [requiresInput.prompt] - Input prompt
+ * @property {Object} [requiresInput.responseSchema] - JSON Schema for response
+ * @property {any} [requiresInput.subject] - Subject shown to the human
+ * @property {string} [requiresInput.resumeToken] - Token to resume workflow
+ * @property {Object} [error] - Error details if failed
+ */
+/**
+ * @typedef {Object} LobsterOptions
+ * @property {Object} [env] - Environment variables
+ * @property {string} [stateDir] - State directory override
+ */
+export class Lobster {
+    #stages = [];
+    #options = {};
+    #meta = null;
+    constructor(options = {}) {
+        this.#options = {
+            env: options.env ?? process.env,
+            stateDir: options.stateDir,
+        };
+    }
+    pipe(stage) {
+        if (typeof stage !== "function" && typeof stage?.run !== "function") {
+            throw new Error("Stage must be a function or have a run() method");
+        }
+        this.#stages.push(stage);
+        return this;
+    }
+    meta(meta) {
+        this.#meta = meta;
+        return this;
+    }
+    getMeta() {
+        return this.#meta;
+    }
+    async run(initialInput = []) {
+        const ctx = {
+            env: this.#options.env,
+            stateDir: this.#options.stateDir,
+            mode: "sdk",
+        };
+        try {
+            const result = await runPipelineInternal({
+                stages: this.#stages,
+                ctx,
+                input: initialInput,
+            });
+            if (result.halted &&
+                result.items.length === 1 &&
+                result.items[0]?.type === "approval_request") {
+                const approval = result.items[0];
+                const resumeToken = encodeToken({
+                    protocolVersion: 1,
+                    v: 1,
+                    stageIndex: result.haltedAt?.index ?? -1,
+                    resumeAtIndex: (result.haltedAt?.index ?? -1) + 1,
+                    items: approval.items,
+                    prompt: approval.prompt,
+                });
+                return {
+                    ok: true,
+                    status: "needs_approval",
+                    output: [],
+                    requiresApproval: {
+                        prompt: approval.prompt,
+                        items: approval.items,
+                        resumeToken,
+                    },
+                    requiresInput: null,
+                };
+            }
+            if (result.halted && result.items.length === 1 && result.items[0]?.type === "input_request") {
+                const input = result.items[0];
+                const resumeMode = input.commandInput ? "same_stage" : "next_stage";
+                const resumeAtIndex = resumeMode === "same_stage"
+                    ? (result.haltedAt?.index ?? -1)
+                    : (result.haltedAt?.index ?? -1) + 1;
+                const stateKey = resumeMode === "same_stage"
+                    ? await saveSdkCommandInputResumeState(this.#options, {
+                        resumeAtIndex,
+                        items: input.items ?? [],
+                        inputSchema: input.responseSchema,
+                        ...(input.subject !== undefined ? { inputSubject: input.subject } : null),
+                        commandInput: input.commandInput,
+                    })
+                    : undefined;
+                const resumeToken = encodeToken({
+                    protocolVersion: 1,
+                    v: 1,
+                    stageIndex: result.haltedAt?.index ?? -1,
+                    resumeAtIndex,
+                    resumeMode,
+                    ...(resumeMode === "same_stage"
+                        ? { stateKey }
+                        : { items: [], inputSchema: input.responseSchema }),
+                    inputSubject: input.subject,
+                });
+                return {
+                    ok: true,
+                    status: "needs_input",
+                    output: [],
+                    requiresApproval: null,
+                    requiresInput: {
+                        prompt: input.prompt,
+                        responseSchema: input.responseSchema,
+                        defaults: input.defaults,
+                        subject: input.subject,
+                        resumeToken,
+                    },
+                };
+            }
+            return {
+                ok: true,
+                status: "ok",
+                output: result.items,
+                requiresApproval: null,
+                requiresInput: null,
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                status: "error",
+                output: [],
+                requiresApproval: null,
+                requiresInput: null,
+                error: {
+                    type: "runtime_error",
+                    message: err?.message ?? String(err),
+                },
+            };
+        }
+    }
+    async resume(token, options = {}) {
+        const { approved, response, cancel } = options;
+        const intentCount = Number(typeof approved === "boolean") +
+            Number(response !== undefined) +
+            Number(cancel === true);
+        if (intentCount > 1) {
+            throw new Error("resume accepts only one of approved, response, or cancel");
+        }
+        if (intentCount === 0) {
+            throw new Error("resume requires approved, response, or cancel");
+        }
+        const payload = decodeSdkResumePayload(token);
+        let sdkCommandInputState;
+        if (payload.resumeMode === "same_stage") {
+            sdkCommandInputState = await loadSdkCommandInputResumeState(this.#options, payload.stateKey);
+        }
+        if (cancel === true) {
+            if (payload.resumeMode === "same_stage") {
+                await deleteStateJson({ env: sdkStateEnv(this.#options), key: payload.stateKey });
+            }
+            return {
+                ok: true,
+                status: "cancelled",
+                output: [],
+                requiresApproval: null,
+                requiresInput: null,
+            };
+        }
+        const expectsInput = payload.inputSchema !== undefined || payload.resumeMode === "same_stage";
+        if (expectsInput) {
+            if (approved !== undefined) {
+                throw new Error("resume token expects an input response, not approved");
+            }
+            if (response === undefined) {
+                throw new Error("resume token expects response");
+            }
+        }
+        else {
+            if (response !== undefined) {
+                throw new Error("resume token expects approved=true|false, not response");
+            }
+            if (typeof approved !== "boolean") {
+                throw new Error("resume token expects approved=true|false");
+            }
+            if (approved === false) {
+                return {
+                    ok: true,
+                    status: "cancelled",
+                    output: [],
+                    requiresApproval: null,
+                    requiresInput: null,
+                };
+            }
+        }
+        const resumeIndex = sdkCommandInputState?.resumeAtIndex ?? payload.resumeAtIndex ?? 0;
+        let resumeItems = sdkCommandInputState?.items ?? payload.items ?? [];
+        let requestInputResume;
+        if (response !== undefined) {
+            const schema = sdkCommandInputState?.inputSchema ?? payload.inputSchema;
+            if (schema === undefined) {
+                throw new Error("resume token does not support input responses");
+            }
+            let validator;
+            try {
+                validator = compileCached(schema);
+            }
+            catch {
+                throw new Error("resume token input schema is invalid");
+            }
+            const ok = validator(response);
+            if (!ok) {
+                const first = validator.errors?.[0];
+                throw new Error(`response does not match schema at ${first?.instancePath || "/"}: ${first?.message || "invalid"}`);
+            }
+            if (payload.resumeMode === "same_stage") {
+                resumeItems = sdkCommandInputState.items;
+                requestInputResume = {
+                    state: sdkCommandInputState.commandInput,
+                    response,
+                    onConsumed: async () => {
+                        await deleteStateJson({ env: sdkStateEnv(this.#options), key: payload.stateKey });
+                    },
+                };
+            }
+            else {
+                resumeItems = [response];
+            }
+        }
+        const remainingStages = this.#stages.slice(resumeIndex);
+        const ctx = {
+            env: this.#options.env,
+            stateDir: this.#options.stateDir,
+            mode: "sdk",
+        };
+        try {
+            const result = await runPipelineInternal({
+                stages: remainingStages,
+                ctx,
+                input: resumeItems,
+                requestInputResume,
+            });
+            if (result.halted &&
+                result.items.length === 1 &&
+                result.items[0]?.type === "approval_request") {
+                const approval = result.items[0];
+                const resumeToken = encodeToken({
+                    protocolVersion: 1,
+                    v: 1,
+                    stageIndex: resumeIndex + (result.haltedAt?.index ?? 0),
+                    resumeAtIndex: resumeIndex + (result.haltedAt?.index ?? 0) + 1,
+                    items: approval.items,
+                    prompt: approval.prompt,
+                });
+                return {
+                    ok: true,
+                    status: "needs_approval",
+                    output: [],
+                    requiresApproval: {
+                        prompt: approval.prompt,
+                        items: approval.items,
+                        resumeToken,
+                    },
+                    requiresInput: null,
+                };
+            }
+            if (result.halted && result.items.length === 1 && result.items[0]?.type === "input_request") {
+                const input = result.items[0];
+                const inputStageIndex = resumeIndex + (result.haltedAt?.index ?? 0);
+                const resumeMode = input.commandInput ? "same_stage" : "next_stage";
+                const stateKey = resumeMode === "same_stage"
+                    ? await saveSdkCommandInputResumeState(this.#options, {
+                        resumeAtIndex: inputStageIndex,
+                        items: input.items ?? [],
+                        inputSchema: input.responseSchema,
+                        ...(input.subject !== undefined ? { inputSubject: input.subject } : null),
+                        commandInput: input.commandInput,
+                    })
+                    : undefined;
+                const resumeToken = encodeToken({
+                    protocolVersion: 1,
+                    v: 1,
+                    stageIndex: inputStageIndex,
+                    resumeAtIndex: resumeMode === "same_stage" ? inputStageIndex : inputStageIndex + 1,
+                    resumeMode,
+                    ...(resumeMode === "same_stage"
+                        ? { stateKey }
+                        : { items: [], inputSchema: input.responseSchema }),
+                    inputSubject: input.subject,
+                });
+                return {
+                    ok: true,
+                    status: "needs_input",
+                    output: [],
+                    requiresApproval: null,
+                    requiresInput: {
+                        prompt: input.prompt,
+                        responseSchema: input.responseSchema,
+                        defaults: input.defaults,
+                        subject: input.subject,
+                        resumeToken,
+                    },
+                };
+            }
+            return {
+                ok: true,
+                status: "ok",
+                output: result.items,
+                requiresApproval: null,
+                requiresInput: null,
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                status: "error",
+                output: [],
+                requiresApproval: null,
+                requiresInput: null,
+                error: {
+                    type: "runtime_error",
+                    message: err?.message ?? String(err),
+                },
+            };
+        }
+    }
+    clone() {
+        const cloned = new Lobster(this.#options);
+        cloned.#stages = [...this.#stages];
+        cloned.#meta = this.#meta ? { ...this.#meta } : null;
+        return cloned;
+    }
+}
+function decodeSdkResumePayload(token) {
+    const payload = decodeToken(token);
+    if (!payload || typeof payload !== "object") {
+        throw new Error("Invalid token");
+    }
+    const data = payload;
+    if (data.protocolVersion !== 1 || data.v !== 1) {
+        throw new Error("Invalid token");
+    }
+    if (typeof data.resumeAtIndex !== "number" ||
+        !Number.isInteger(data.resumeAtIndex) ||
+        data.resumeAtIndex < 0) {
+        throw new Error("Invalid token");
+    }
+    if (data.items !== undefined && !Array.isArray(data.items)) {
+        throw new Error("Invalid token");
+    }
+    if (data.resumeMode !== undefined &&
+        (typeof data.resumeMode !== "string" || !["next_stage", "same_stage"].includes(data.resumeMode))) {
+        throw new Error("Invalid token");
+    }
+    if (data.resumeMode === "same_stage") {
+        if (typeof data.stateKey !== "string" || data.stateKey.length === 0) {
+            throw new Error("Invalid token");
+        }
+    }
+    else if (data.stateKey !== undefined) {
+        throw new Error("Invalid token");
+    }
+    if (data.commandInput !== undefined)
+        throw new Error("Invalid token");
+    return data;
+}
+function sdkStateEnv(options) {
+    return options.stateDir
+        ? { ...(options.env ?? process.env), LOBSTER_STATE_DIR: options.stateDir }
+        : (options.env ?? process.env);
+}
+async function saveSdkCommandInputResumeState(options, state) {
+    const stateKey = `sdk_resume_${randomUUID()}`;
+    await writeStateJson({ env: sdkStateEnv(options), key: stateKey, value: state });
+    return stateKey;
+}
+async function loadSdkCommandInputResumeState(options, stateKey) {
+    const stored = await readStateJson({ env: sdkStateEnv(options), key: stateKey });
+    if (!stored || typeof stored !== "object")
+        throw new Error("SDK resume state not found");
+    const data = stored;
+    if (typeof data.resumeAtIndex !== "number" ||
+        !Number.isInteger(data.resumeAtIndex) ||
+        data.resumeAtIndex < 0) {
+        throw new Error("Invalid SDK resume state");
+    }
+    if (!Array.isArray(data.items))
+        throw new Error("Invalid SDK resume state");
+    if (data.inputSchema === undefined)
+        throw new Error("Invalid SDK resume state");
+    data.commandInput = validateCommandInputState(data.commandInput);
+    return data;
+}
+//# sourceMappingURL=Lobster.js.map

package/dist/src/sdk/Lobster.js.map

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

package/dist/src/sdk/index.js

@@ -0,0 +1,25 @@
+/**
+ * Lobster SDK - Workflow runtime for AI agents
+ *
+ * @example
+ * import { Lobster, approve, exec } from 'lobster-sdk';
+ *
+ * const workflow = new Lobster()
+ *   .pipe(exec('gh pr view 123 --repo owner/repo --json title,url'))
+ *   .pipe(items => items.filter(e => e.unread))
+ *   .pipe(approve({ prompt: 'Process these emails?' }))
+ *   .pipe(async function* (items) {
+ *     for (const item of items) {
+ *       yield { ...item, processed: true };
+ *     }
+ *   });
+ *
+ * const result = await workflow.run();
+ */
+export { Lobster } from "./Lobster.js";
+export { approve } from "./primitives/approve.js";
+export { exec } from "./primitives/exec.js";
+export { stateGet, stateSet, state } from "./primitives/state.js";
+export { diffLast } from "./primitives/diff.js";
+export { runPipeline } from "./runtime.js";
+//# sourceMappingURL=index.js.map

package/dist/src/sdk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC"}

package/dist/src/sdk/primitives/approve.js

@@ -0,0 +1,47 @@
+/**
+ * Approve primitive - Creates a hard halt point requiring human approval
+ *
+ * @example
+ * import { Lobster, approve } from 'lobster-sdk';
+ *
+ * new Lobster()
+ *   .pipe(fetchEmails())
+ *   .pipe(approve({ prompt: 'Send these replies?' }))
+ *   .pipe(sendReplies())
+ */
+/**
+ * Create an approval stage
+ *
+ * @param {Object} [options]
+ * @param {string} [options.prompt='Approve?'] - Prompt to show user
+ * @param {boolean} [options.preview=true] - Include items in approval request
+ * @returns {Object} Stage object with run method
+ */
+export function approve(options = {}) {
+    const prompt = options.prompt ?? "Approve?";
+    const preview = options.preview !== false;
+    return {
+        type: "approve",
+        prompt,
+        async run({ input, ctx: _ctx }) {
+            // Collect all items
+            const items = [];
+            for await (const item of input) {
+                items.push(item);
+            }
+            // In SDK mode, always emit approval request and halt
+            return {
+                halt: true,
+                output: (async function* () {
+                    yield {
+                        type: "approval_request",
+                        prompt,
+                        items: preview ? items : [],
+                        itemCount: items.length,
+                    };
+                })(),
+            };
+        },
+    };
+}
+//# sourceMappingURL=approve.js.map

package/dist/src/sdk/primitives/approve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approve.js","sourceRoot":"","sources":["../../../../src/sdk/primitives/approve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAC,OAAO,GAAQ,EAAE;IACvC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,UAAU,CAAC;IAC5C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,KAAK,KAAK,CAAC;IAE1C,OAAO;QACL,IAAI,EAAE,SAAS;QACf,MAAM;QAEN,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE;YAC5B,oBAAoB;YACpB,MAAM,KAAK,GAAG,EAAE,CAAC;YACjB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBAC/B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;YAED,qDAAqD;YACrD,OAAO;gBACL,IAAI,EAAE,IAAI;gBACV,MAAM,EAAE,CAAC,KAAK,SAAS,CAAC;oBACtB,MAAM;wBACJ,IAAI,EAAE,kBAAkB;wBACxB,MAAM;wBACN,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;wBAC3B,SAAS,EAAE,KAAK,CAAC,MAAM;qBACxB,CAAC;gBACJ,CAAC,CAAC,EAAE;aACL,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/sdk/primitives/diff.js

@@ -0,0 +1,156 @@
+/**
+ * Diff primitive - Compare current value against last stored value
+ *
+ * @example
+ * import { Lobster, diffLast } from 'lobster-sdk';
+ *
+ * new Lobster()
+ *   .pipe(fetchPRStatus())
+ *   .pipe(diffLast('pr-123'))
+ *   .pipe(result => {
+ *     if (result.changed) {
+ *       console.log('PR changed!', result.changes);
+ *     }
+ *   });
+ */
+import { promises as fsp } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ensureDirectory, isJsonSyntaxError, writeFileAtomic } from "../../state/store.js";
+/**
+ * Get the state directory
+ * @param {Object} ctx
+ * @returns {string}
+ */
+function getStateDir(ctx) {
+    return (ctx?.stateDir ||
+        (ctx?.env?.LOBSTER_STATE_DIR && String(ctx.env.LOBSTER_STATE_DIR).trim()) ||
+        path.join(os.homedir(), ".lobster", "state"));
+}
+/**
+ * Convert a key to a safe file path
+ * @param {string} stateDir
+ * @param {string} key
+ * @returns {string}
+ */
+function keyToPath(stateDir, key) {
+    const safe = String(key)
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (!safe)
+        throw new Error("state key is empty/invalid");
+    return path.join(stateDir, `${safe}.json`);
+}
+/**
+ * Stable JSON stringify for comparison
+ * @param {any} value
+ * @returns {string}
+ */
+function stableStringify(value) {
+    return JSON.stringify(value, (_k, v) => {
+        if (v && typeof v === "object" && !Array.isArray(v)) {
+            return Object.fromEntries(Object.keys(v)
+                .sort()
+                .map((k) => [k, v[k]]));
+        }
+        return v;
+    });
+}
+/**
+ * Create a diff.last stage
+ *
+ * Compares the input against the last stored value for the given key,
+ * stores the new value, and outputs a diff result.
+ *
+ * @param {string} key - State key to compare against
+ * @param {Object} [options]
+ * @param {boolean} [options.changesOnly=false] - If true, suppress output when unchanged
+ * @returns {Object} Stage object with run method
+ */
+export function diffLast(key, options = {}) {
+    if (!key)
+        throw new Error("diffLast requires a key");
+    const changesOnly = options.changesOnly === true;
+    return {
+        type: "diff.last",
+        key,
+        async run({ input, ctx }) {
+            // Collect all input items
+            const items = [];
+            for await (const item of input) {
+                items.push(item);
+            }
+            const value = items.length === 1 ? items[0] : items;
+            const stateDir = getStateDir(ctx);
+            const filePath = keyToPath(stateDir, key);
+            // Read previous value
+            let before = null;
+            try {
+                const text = await fsp.readFile(filePath, "utf8");
+                before = JSON.parse(text);
+            }
+            catch (err) {
+                if (err?.code !== "ENOENT" && !isJsonSyntaxError(err)) {
+                    throw err;
+                }
+            }
+            // Compare
+            const changed = stableStringify(before) !== stableStringify(value);
+            // Store new value
+            await ensureDirectory(stateDir);
+            await writeFileAtomic(filePath, JSON.stringify(value, null, 2) + "\n");
+            // Build result
+            const result = {
+                kind: "diff.last",
+                key,
+                changed,
+                before,
+                after: value,
+            };
+            // If changesOnly and no change, output suppressed marker
+            if (changesOnly && !changed) {
+                return {
+                    output: (async function* () {
+                        yield { kind: "diff.last", key, changed: false, suppressed: true };
+                    })(),
+                };
+            }
+            return {
+                output: (async function* () {
+                    yield result;
+                })(),
+            };
+        },
+    };
+}
+/**
+ * Diff and store directly (not as a pipeline stage)
+ * @param {string} key
+ * @param {any} value
+ * @param {Object} [ctx]
+ * @returns {Promise<{before: any, after: any, changed: boolean}>}
+ */
+export async function diffAndStoreValue(key, value, ctx = {}) {
+    const stateDir = getStateDir(ctx);
+    const filePath = keyToPath(stateDir, key);
+    // Read previous value
+    let before = null;
+    try {
+        const text = await fsp.readFile(filePath, "utf8");
+        before = JSON.parse(text);
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT" && !isJsonSyntaxError(err)) {
+            throw err;
+        }
+    }
+    // Compare
+    const changed = stableStringify(before) !== stableStringify(value);
+    // Store new value
+    await ensureDirectory(stateDir);
+    await writeFileAtomic(filePath, JSON.stringify(value, null, 2) + "\n");
+    return { before, after: value, changed };
+}
+//# sourceMappingURL=diff.js.map

package/dist/src/sdk/primitives/diff.js.map

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