@xyne/workflow-sdk 3.2.34 → 3.2.36

package/dist/agents/contract.js

@@ -0,0 +1,196 @@
+/**
+ * Agent contract — the half of an agent step that holds regardless of who
+ * actually runs the agent.
+ *
+ * An agent step has two halves:
+ *
+ *  - The **provider half** is specific to the agent platform behind the step:
+ *    prompts, tools and turn limits for an SDK-driven LLM ({@link AgentStep});
+ *    an agent id for a host that owns its own agent lifecycle
+ *    ({@link HostAgentStep}).
+ *  - The **contract half** is the workflow's agreement with the step: what
+ *    shape the output takes, whether it must be JSON, whether it carries
+ *    citations, and how many times an unusable response is re-prompted before
+ *    the step gives up. That is what lives here.
+ *
+ * Both steps compose the same {@link agentContractFields} and produce the same
+ * {@link AgentResult}, so a workflow can move between them without rewriting
+ * downstream `{{steps.x.output.response}}` refs.
+ *
+ * Deliberately free of pi-mono imports: a host-backed agent step must be able
+ * to use this without pulling the LLM runtime into the bundle.
+ */
+import { z } from 'zod';
+import { AttachmentSchema, ATTACHMENT_ARRAY_JSON_SCHEMA } from '../common/attachment.js';
+import { variableRef } from '../types/workflow-config.js';
+import { splitCitedResponse } from './citation-resolve.js';
+// ─── Contract Config Fields ───
+/**
+ * The contract fields whose wording is identical for every agent step.
+ *
+ * Exposed as a field map rather than a `z.object` so each step can interleave
+ * them with its own fields in whatever order reads best in the form — the
+ * generic renderer follows declaration order, so composing with `.merge()`
+ * would force all contract fields to the bottom.
+ */
+export const agentContractFields = {
+    outputType: z.enum(['string', 'json']).default('string')
+        .describe('Shape of the agent response: free text, or a JSON object matching outputSchema'),
+    outputSchema: variableRef(z.record(z.unknown())).optional()
+        .describe('When outputType is "json", the JSON Schema the response object should match'),
+    cite: z.boolean().default(false)
+        .describe('Require the agent to cite the source of every data point it produces'),
+    timeoutMs: z.number().int().positive().default(1_200_000)
+        .describe('Max wall-clock time for the agent run in milliseconds. Default: 1200000 (20 minutes).'),
+};
+/**
+ * Input documents field. The type is shared; the copy is not — how an agent
+ * receives its documents differs by provider (the SDK's LLM step mounts them
+ * into a sandbox; a host agent is handed refs), and the field's help text is
+ * the only place an author learns which.
+ */
+export function attachmentsField(description) {
+    return variableRef(z.array(AttachmentSchema).describe(description)).optional();
+}
+/**
+ * Repair budget field. Same reasoning as {@link attachmentsField}: the bound
+ * and default are the contract, the description names the mechanism, which
+ * differs (re-prompting one conversation vs. re-running an agent).
+ */
+export function jsonRepairRetriesField(description) {
+    return z.number().int().min(0).default(3).describe(description);
+}
+/**
+ * The output shape both agent steps declare. Downstream refs bind against
+ * this, so it must not diverge between them.
+ */
+export const AgentResultSchema = z.object({
+    response: z.union([z.string(), z.record(z.unknown())]),
+    toolCalls: z.array(z.object({
+        name: z.string(),
+        args: z.record(z.unknown()),
+        result: z.unknown(),
+        durationMs: z.number(),
+    })),
+    turnCount: z.number(),
+    usage: z.object({
+        inputTokens: z.number(),
+        outputTokens: z.number(),
+    }),
+    attachments: z.array(AttachmentSchema),
+});
+// ─── Utility ───
+export function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Reject `promise` if it has not settled within `timeoutMs`.
+ *
+ * `label` names what timed out — tool execution for the LLM step, the whole
+ * agent run for a host-backed one — so the error text stays accurate wherever
+ * this is applied.
+ */
+export function withTimeout(promise, timeoutMs, label = 'Tool execution') {
+    return Promise.race([
+        promise,
+        new Promise((_resolve, reject) => {
+            const timer = setTimeout(() => { reject(new Error(`${label} timed out after ${timeoutMs}ms`)); }, timeoutMs);
+            // Don't block Node from exiting
+            if (typeof timer === 'object' && 'unref' in timer) {
+                timer.unref();
+            }
+        }),
+    ]);
+}
+/**
+ * Classify a response for the repair loop: `ok`, or not-ok with the reason —
+ * `empty` (nothing to parse) or `unparseable` (JSON.parse threw, with the
+ * error text so it can be fed back to the model).
+ */
+export function classifyResponse(raw, expectJson) {
+    const trimmed = raw.trim();
+    // An empty response is always a failure — regardless of output type.
+    if (trimmed.length === 0)
+        return { ok: false, reason: 'empty' };
+    // For non-JSON outputs, any non-empty text is acceptable.
+    if (!expectJson)
+        return { ok: true };
+    const unfenced = stripCodeFence(trimmed);
+    if (unfenced.length === 0)
+        return { ok: false, reason: 'empty' };
+    try {
+        JSON.parse(unfenced);
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, reason: 'unparseable', error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/**
+ * Parse a JSON-mode agent response into an object. Strips Markdown code fences
+ * the model may wrap around the JSON. Falls back to `{ text }` if the response
+ * isn't valid JSON or isn't an object, so the output always matches the
+ * declared object shape.
+ */
+export function parseJsonResponse(raw) {
+    const unfenced = stripCodeFence(raw.trim());
+    try {
+        const parsed = JSON.parse(unfenced);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return { value: parsed };
+    }
+    catch {
+        return { text: raw };
+    }
+}
+function stripCodeFence(text) {
+    return text
+        .replace(/^```(?:json)?\s*/i, '')
+        .replace(/\s*```$/, '')
+        .trim();
+}
+// ─── Output Shaping ───
+/**
+ * Shape a raw agent response per `outputType` — parse JSON when requested, and
+ * split out citations when `cite` is on.
+ */
+export function shapeAgentResponse(raw, opts, log) {
+    if (opts.outputType !== 'json' || typeof raw !== 'string')
+        return raw;
+    const parsed = parseJsonResponse(raw);
+    return opts.cite ? splitCitedResponse(parsed, log) : parsed;
+}
+/**
+ * Resolve the declared output JSON Schema for an agent step instance.
+ *
+ * With citations on the agent returns `{value, citation}`, so downstream refs
+ * and layouts address `output.response.value.*`. Gating the schema on the same
+ * flag as the runtime split keeps the declared and actual shapes in step —
+ * they flip together, per step, or not at all.
+ */
+export function resolveAgentOutputJsonSchema(config) {
+    const outputType = config['outputType'] === 'json' ? 'json' : 'string';
+    const rawSchema = config['outputSchema'];
+    const userSchema = isRecord(rawSchema) ? rawSchema : undefined;
+    let response = outputType === 'json'
+        ? (userSchema && Object.keys(userSchema).length > 0 ? userSchema : { type: 'object' })
+        : { type: 'string' };
+    if (outputType === 'json' && config['cite'] === true) {
+        response = {
+            type: 'object',
+            properties: { value: response, citation: { type: 'object' } },
+        };
+    }
+    return {
+        type: 'object',
+        properties: {
+            response,
+            attachments: ATTACHMENT_ARRAY_JSON_SCHEMA,
+            toolCalls: { type: 'array' },
+            usage: { type: 'object' },
+        },
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/agents/contract.js.map

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

package/dist/agents/host-agent-step.d.ts

@@ -0,0 +1,222 @@
+/**
+ * HostAgentStep — runs an agent the *host* owns, rather than one the SDK
+ * drives.
+ *
+ * Where {@link AgentStep} asks an author to construct an agent (system prompt,
+ * tools, model, turn budget), this asks them to choose one and give it a task.
+ * Everything about how that agent behaves — its prompt, its tools, its MCP
+ * connections — is resolved by the host's own agent platform behind a
+ * {@link BaseAgentProvider}.
+ *
+ * What stays here is the workflow's contract with the step, and it is identical
+ * to the LLM step's: the declared output shape, JSON repair, citation
+ * splitting, and artifact persistence. Both steps emit the same
+ * {@link AgentResult}, so downstream `{{steps.x.output.response}}` refs bind
+ * the same way against either.
+ *
+ * Registered by the host with its own naming, so a deployment shows the step
+ * in the author's vocabulary:
+ *
+ *     new HostAgentStep(new ClawAgentProvider(deps), {
+ *       type: 'RUN_XYNE_AGENT',
+ *       name: 'Run Xyne Agent',
+ *       description: 'Run an agent from your workspace',
+ *     })
+ *
+ * Free of pi-mono imports — a host registering only this step does not pull the
+ * LLM runtime into its bundle.
+ */
+import { z } from 'zod';
+import { BaseActionStep } from '../steps/base-step.js';
+import type { StepExecutionContext } from '../steps/base-step.js';
+import type { StepType } from '../types/step-types.js';
+import type { StepCategory } from '../types/categories.js';
+import type { AgentResult } from './contract.js';
+import type { BaseAgentProvider } from './provider.js';
+declare const HostAgentBaseSchema: z.ZodObject<{
+    attachments: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        mimeType: z.ZodString;
+        data: z.ZodString;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        mimeType: string;
+        data: string;
+        size?: number | undefined;
+    }, {
+        name: string;
+        mimeType: string;
+        data: string;
+        size?: number | undefined;
+    }>, "many">, z.ZodString]>>;
+    outputType: z.ZodDefault<z.ZodEnum<["string", "json"]>>;
+    outputSchema: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    cite: z.ZodDefault<z.ZodBoolean>;
+    jsonRepairRetries: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    task: z.ZodString;
+    mode: z.ZodDefault<z.ZodEnum<["sync", "async"]>>;
+}, "strip", z.ZodTypeAny, {
+    timeoutMs: number;
+    mode: "sync" | "async";
+    outputType: "string" | "json";
+    cite: boolean;
+    jsonRepairRetries: number;
+    task: string;
+    outputSchema?: string | Record<string, unknown> | undefined;
+    attachments?: string | {
+        name: string;
+        mimeType: string;
+        data: string;
+        size?: number | undefined;
+    }[] | undefined;
+}, {
+    task: string;
+    timeoutMs?: number | undefined;
+    mode?: "sync" | "async" | undefined;
+    outputSchema?: string | Record<string, unknown> | undefined;
+    attachments?: string | {
+        name: string;
+        mimeType: string;
+        data: string;
+        size?: number | undefined;
+    }[] | undefined;
+    outputType?: "string" | "json" | undefined;
+    cite?: boolean | undefined;
+    jsonRepairRetries?: number | undefined;
+}>;
+export type HostAgentBaseConfig = z.infer<typeof HostAgentBaseSchema>;
+/**
+ * How the step presents itself in the builder. All optional — the defaults
+ * describe a generic host agent, which is right when a deployment registers
+ * exactly one.
+ */
+export interface HostAgentStepOptions {
+    type?: StepType;
+    name?: string;
+    description?: string;
+    icon?: string;
+    category?: StepCategory;
+}
+export declare class HostAgentStep<TProviderConfig extends z.AnyZodObject = z.AnyZodObject> extends BaseActionStep<z.AnyZodObject, AgentResult> {
+    private readonly provider;
+    readonly type: StepType;
+    readonly name: string;
+    readonly description: string;
+    readonly category: StepCategory;
+    readonly icon?: string;
+    readonly configSchema: z.AnyZodObject;
+    readonly outputSchema: z.ZodObject<{
+        response: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+        toolCalls: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            result: z.ZodUnknown;
+            durationMs: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            args: Record<string, unknown>;
+            durationMs: number;
+            result?: unknown;
+        }, {
+            name: string;
+            args: Record<string, unknown>;
+            durationMs: number;
+            result?: unknown;
+        }>, "many">;
+        turnCount: z.ZodNumber;
+        usage: z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            inputTokens: number;
+            outputTokens: number;
+        }, {
+            inputTokens: number;
+            outputTokens: number;
+        }>;
+        attachments: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            mimeType: z.ZodString;
+            data: z.ZodString;
+            size: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }, {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        response: string | Record<string, unknown>;
+        attachments: {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }[];
+        toolCalls: {
+            name: string;
+            args: Record<string, unknown>;
+            durationMs: number;
+            result?: unknown;
+        }[];
+        turnCount: number;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    }, {
+        response: string | Record<string, unknown>;
+        attachments: {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }[];
+        toolCalls: {
+            name: string;
+            args: Record<string, unknown>;
+            durationMs: number;
+            result?: unknown;
+        }[];
+        turnCount: number;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    }>;
+    constructor(provider: BaseAgentProvider<TProviderConfig, unknown>, options?: HostAgentStepOptions);
+    decorateConfigSchema(jsonSchema: Record<string, unknown>): Record<string, unknown>;
+    resolveOutputJsonSchema(config: Record<string, unknown>): Record<string, unknown>;
+    execute(rawConfig: Record<string, unknown>, ctx: StepExecutionContext): Promise<AgentResult>;
+    /**
+     * Resume after a dispatched run reported back.
+     *
+     * This is where the repair loop lives for background runs. It cannot be a
+     * loop the way the streaming path is — each attempt crosses a pause boundary,
+     * so the budget is carried on the step record and the loop is re-entry.
+     */
+    onResume(rowData: Record<string, unknown>, rawConfig: Record<string, unknown>, ctx: StepExecutionContext): Promise<AgentResult>;
+    /**
+     * Hand the run to the provider and park the step. Never returns — `ctx.pause`
+     * throws, releasing the worker slot until the host calls back.
+     */
+    private dispatch;
+    /** Run the agent inline, streaming progress, repairing in a loop. */
+    private runStreaming;
+    private buildInput;
+    private finalize;
+    /**
+     * Drive one streamed run to completion: forward progress to the execution
+     * viewer, persist artifacts, and return the result the provider reported.
+     */
+    private consume;
+}
+export {};
+//# sourceMappingURL=host-agent-step.d.ts.map

package/dist/agents/host-agent-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-agent-step.d.ts","sourceRoot":"","sources":["../../src/agents/host-agent-step.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAa3D,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,eAAe,CAAC;AAGjE,OAAO,KAAK,EAKV,iBAAiB,EAClB,MAAM,eAAe,CAAC;AAoCvB,QAAA,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAIvB,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AA0BtE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAID,qBAAa,aAAa,CACxB,eAAe,SAAS,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CACvD,SAAQ,cAAc,CAAC,CAAC,CAAC,YAAY,EAAE,WAAW,CAAC;IAUjD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAT3B,SAAkB,IAAI,EAAE,QAAQ,CAAC;IACjC,SAAkB,IAAI,EAAE,MAAM,CAAC;IAC/B,SAAkB,WAAW,EAAE,MAAM,CAAC;IACtC,SAAkB,QAAQ,EAAE,YAAY,CAAC;IACzC,SAAiB,IAAI,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAkB,YAAY,EAAE,CAAC,CAAC,YAAY,CAAC;IAC/C,SAAkB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAqB;gBAGhC,QAAQ,EAAE,iBAAiB,CAAC,eAAe,EAAE,OAAO,CAAC,EACtE,OAAO,GAAE,oBAAyB;IAmB3B,oBAAoB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAWlF,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI3E,OAAO,CACpB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,WAAW,CAAC;IAOvB;;;;;;OAMG;IACY,QAAQ,CACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,WAAW,CAAC;IAmEvB;;;OAGG;YACW,QAAQ;IAwBtB,qEAAqE;YACvD,YAAY;IA2E1B,OAAO,CAAC,UAAU;IAqBlB,OAAO,CAAC,QAAQ;IAmBhB;;;OAGG;YACW,OAAO;CAyEtB"}