@loxtep/sdk 0.2.3 → 0.4.0

package/dist/authoring/compiler.js

@@ -0,0 +1,305 @@
+/**
+ * Pure deploy compiler — `compileModule`
+ *
+ * Lowers a `DataWorkflowModule` into `GraphPatchOp[]` mirroring the backend's
+ * `graph-patch-apply.ts` shape. This is a pure function: no I/O, no network.
+ *
+ * Responsibilities:
+ * - Trigger → connection/ingestion node
+ * - Handler steps → transform node(s)
+ * - Sinks → data-product node(s)
+ * - Resolve `workflow_id` by name for in-place update (R3.5)
+ * - Collect `referencedResources` for pre-deploy existence validation (R1.8)
+ * - Compute removal set: modules on instance but absent from project (R3.7)
+ *
+ * Requirements: 3.4, 3.5, 3.7
+ */
+// ────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ────────────────────────────────────────────────────────────────────────────
+/** Generate a deterministic node ID from module name + a suffix. */
+function nodeId(workflowName, suffix) {
+    return `${workflowName}__${suffix}`;
+}
+/**
+ * Lower a single trigger into a connection/ingestion node + graph ops.
+ * Returns the entity_id of the created node so downstream nodes can connect.
+ */
+function lowerTrigger(trigger, workflowName, index) {
+    const entityId = nodeId(workflowName, `trigger_${index}`);
+    const refs = [];
+    const entity = {
+        connection_id: entityId,
+        name: `${workflowName}_trigger_${index}`,
+        trigger_kind: trigger.kind,
+    };
+    if (trigger.ref) {
+        entity.source_id = trigger.ref.id;
+        entity.source_name = trigger.ref.name;
+        // Collect the resource reference
+        if (trigger.kind === 'queue') {
+            refs.push({ type: 'queue', id: trigger.ref.id, name: trigger.ref.name });
+        }
+        else if (trigger.kind === 'connector') {
+            refs.push({ type: 'connector', id: trigger.ref.id, name: trigger.ref.name });
+        }
+    }
+    if (trigger.schedule) {
+        entity.schedule = trigger.schedule;
+    }
+    if (trigger.path) {
+        entity.webhook_path = trigger.path;
+    }
+    const ops = [
+        { op: 'add_node', entity_type: 'connections', entity },
+    ];
+    return { ops, entityId, refs };
+}
+/**
+ * Lower the handler into a single transform node.
+ * The handler itself is stored as a reference (name-based) — the actual execution
+ * is handled at runtime by the deployed bot, not baked into the graph.
+ */
+function lowerHandler(workflowName) {
+    const entityId = nodeId(workflowName, 'handler');
+    const entity = {
+        transformation_id: entityId,
+        name: `${workflowName}_handler`,
+        transform_type: 'code_handler',
+        module_name: workflowName,
+    };
+    const ops = [
+        { op: 'add_node', entity_type: 'transformations', entity },
+    ];
+    return { ops, entityId };
+}
+/**
+ * Resolve the `workflow_id` for a module by name from the NormalizedContext.
+ * If a workflow with the same name exists, returns its id for in-place update (R3.5).
+ */
+function resolveWorkflowId(workflowName, ctx) {
+    const match = ctx.workflows.find((w) => w.data.name === workflowName);
+    return match?.data.id;
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Node compile-time validation (R10.3)
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Validate declared nodes before lowering. Fail fast if:
+ * 1. Any node has an `upstream` that cannot be resolved to a known node name
+ * 2. Any ApprovalNodeSpec lacks at least one labeled downstream connection
+ *
+ * The `knownNames` map is seeded with trigger/handler names before this runs,
+ * and we also consider other declared node names as valid references.
+ */
+function validateNodes(nodes, seedNames) {
+    // Build the full set of known names: seed names (triggers, handler) + all declared node names
+    const knownNames = new Set(seedNames.keys());
+    for (const node of nodes) {
+        knownNames.add(node.name);
+    }
+    for (const node of nodes) {
+        // Validate upstream is resolvable
+        if (!knownNames.has(node.upstream)) {
+            throw new Error(`Node "${node.name}" has upstream "${node.upstream}" which does not resolve to any known node.`);
+        }
+        // Validate ApprovalNodeSpec has at least one labeled downstream
+        if (node.kind === 'approval') {
+            if (!node.approved && !node.rejected) {
+                throw new Error(`Approval node "${node.name}" must have at least one labeled downstream connection (approved or rejected).`);
+            }
+        }
+    }
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Node lowering helpers
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Lower the `nodes` array from a DataWorkflowModule into graph patch ops.
+ *
+ * For each declared node:
+ * - Emits an `add_node` op with the correct entity_type and config
+ * - Emits a `connect_nodes` op from the resolved upstream node
+ * - For ApprovalNodeSpec: emits `connect_nodes_labeled` for approved/rejected paths
+ * - For AgentNodeSpec: emits `connect_nodes_labeled` for error path
+ *
+ * The `nameToEntityId` map provides resolution of node names to entity_ids,
+ * seeded with trigger and handler entity ids before processing nodes.
+ */
+function lowerNodes(nodes, workflowName, nameToEntityId) {
+    const ops = [];
+    // First pass: assign entity_ids for all declared nodes so cross-references resolve
+    for (const node of nodes) {
+        const entityId = nodeId(workflowName, `node_${node.name}`);
+        nameToEntityId.set(node.name, entityId);
+    }
+    // Second pass: emit ops for each node
+    for (const node of nodes) {
+        const entityId = nameToEntityId.get(node.name);
+        if (node.kind === 'approval') {
+            // Emit add_node for approval
+            const entity = {
+                approval_node_id: entityId,
+                name: node.name,
+                approval_channel: node.approvalChannel,
+                timeout_hours: node.timeoutHours,
+            };
+            if (node.description !== undefined) {
+                entity.description = node.description;
+            }
+            ops.push({ op: 'add_node', entity_type: 'approvals', entity });
+            // Emit connect_nodes from upstream
+            const upstreamId = nameToEntityId.get(node.upstream);
+            if (upstreamId) {
+                ops.push({ op: 'connect_nodes', from_entity_id: upstreamId, to_entity_id: entityId });
+            }
+            // Emit connect_nodes_labeled for approved path
+            if (node.approved) {
+                const approvedId = nameToEntityId.get(node.approved);
+                if (approvedId) {
+                    ops.push({
+                        op: 'connect_nodes_labeled',
+                        from_entity_id: entityId,
+                        to_entity_id: approvedId,
+                        label: 'approved',
+                    });
+                }
+            }
+            // Emit connect_nodes_labeled for rejected path
+            if (node.rejected) {
+                const rejectedId = nameToEntityId.get(node.rejected);
+                if (rejectedId) {
+                    ops.push({
+                        op: 'connect_nodes_labeled',
+                        from_entity_id: entityId,
+                        to_entity_id: rejectedId,
+                        label: 'rejected',
+                    });
+                }
+            }
+        }
+        else if (node.kind === 'agent') {
+            // Emit add_node for agent
+            const entity = {
+                agent_node_id: entityId,
+                name: node.name,
+                model_id: node.modelId,
+                prompt_template: node.promptTemplate,
+                timeout_seconds: node.timeoutSeconds ?? 30,
+            };
+            if (node.outputSchema !== undefined) {
+                entity.output_schema = node.outputSchema;
+            }
+            if (node.description !== undefined) {
+                entity.description = node.description;
+            }
+            ops.push({ op: 'add_node', entity_type: 'agents', entity });
+            // Emit connect_nodes from upstream
+            const upstreamId = nameToEntityId.get(node.upstream);
+            if (upstreamId) {
+                ops.push({ op: 'connect_nodes', from_entity_id: upstreamId, to_entity_id: entityId });
+            }
+            // Emit connect_nodes_labeled for error path
+            if (node.error) {
+                const errorId = nameToEntityId.get(node.error);
+                if (errorId) {
+                    ops.push({
+                        op: 'connect_nodes_labeled',
+                        from_entity_id: entityId,
+                        to_entity_id: errorId,
+                        label: 'error',
+                    });
+                }
+            }
+        }
+    }
+    return { ops };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Public API
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Compile a single `DataWorkflowModule` into a `CompiledWorkflow`.
+ *
+ * This is a **pure function**: it performs no I/O, no network calls. Given the
+ * same module and context, it always produces the same output.
+ *
+ * Graph lowering:
+ * - Each trigger → a `connections` (ingestion) node
+ * - The handler → a `transformations` node
+ * - All trigger nodes connect to the handler node
+ *
+ * @param mod - The data workflow module to compile
+ * @param ctx - The normalized workspace context (provides workflow identity lookup)
+ * @returns A `CompiledWorkflow` with ops, referencedResources, and optional workflow_id
+ */
+export function compileModule(mod, ctx) {
+    const ops = [];
+    const referencedResources = [];
+    // Resolve workflow identity for in-place update (R3.5)
+    const workflow_id = resolveWorkflowId(mod.name, ctx);
+    // Lower each trigger into a connection/ingestion node
+    const triggerEntityIds = [];
+    for (let i = 0; i < mod.triggers.length; i++) {
+        const trigger = mod.triggers[i];
+        const result = lowerTrigger(trigger, mod.name, i);
+        ops.push(...result.ops);
+        triggerEntityIds.push(result.entityId);
+        referencedResources.push(...result.refs);
+    }
+    // Lower handler into a transform node
+    const handler = lowerHandler(mod.name);
+    ops.push(...handler.ops);
+    // Connect each trigger node to the handler node
+    for (const triggerId of triggerEntityIds) {
+        ops.push({
+            op: 'connect_nodes',
+            from_entity_id: triggerId,
+            to_entity_id: handler.entityId,
+        });
+    }
+    // Lower declarative nodes (approval gates, agent invocations) if present (R9.3, R9.4, R10.1, R10.2)
+    if (mod.nodes && mod.nodes.length > 0) {
+        // Build name-to-entityId map seeded with trigger/handler nodes
+        const nameToEntityId = new Map();
+        // Register trigger nodes by their constructed names (trigger_0, trigger_1, ...)
+        for (let i = 0; i < triggerEntityIds.length; i++) {
+            nameToEntityId.set(`trigger_${i}`, triggerEntityIds[i]);
+        }
+        // Register the handler node
+        nameToEntityId.set('handler', handler.entityId);
+        // Compile-time validation (R10.3): fail fast before emitting ops
+        validateNodes(mod.nodes, nameToEntityId);
+        const nodeResult = lowerNodes(mod.nodes, mod.name, nameToEntityId);
+        ops.push(...nodeResult.ops);
+    }
+    return {
+        name: mod.name,
+        ...(workflow_id !== undefined ? { workflow_id } : {}),
+        ops,
+        referencedResources,
+    };
+}
+/**
+ * Compute the removal set: workflows present on the instance but absent from
+ * the current set of project modules (R3.7).
+ *
+ * Returns `remove_node` operations for each workflow that should be deleted,
+ * along with the workflow identities (name + id) for reporting.
+ *
+ * @param projectModuleNames - The set of module names currently in the project
+ * @param ctx - The normalized workspace context (contains instance workflows)
+ * @returns An object with removal ops and the names/ids of removed workflows
+ */
+export function computeRemovalSet(projectModuleNames, ctx) {
+    const removals = [];
+    const ops = [];
+    for (const wf of ctx.workflows) {
+        if (!projectModuleNames.has(wf.data.name)) {
+            removals.push({ name: wf.data.name, workflow_id: wf.data.id });
+            ops.push({ op: 'remove_node', entity_id: wf.data.id });
+        }
+    }
+    return { removals, ops };
+}
+//# sourceMappingURL=compiler.js.map

package/dist/authoring/compiler.js.map

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

package/dist/authoring/define-data-workflow.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `defineDataWorkflow` factory — the core code-first authoring entry point.
+ *
+ * Validates the module specification synchronously using zod and throws a
+ * `ValidationError` naming the invalid argument on failure.
+ */
+import type { DataWorkflowModule } from './types.js';
+/**
+ * Validates a `DataWorkflowModule` specification and returns it unchanged.
+ *
+ * Throws `ValidationError` (from `@loxtep/sdk/errors`) with a `field_errors`
+ * entry naming the invalid argument when validation fails.
+ *
+ * Validation rules:
+ * - `name`: 1–64 characters (R3.1, R3.8)
+ * - `triggers`: at least 1 and at most 10 entries (R3.1, R3.8)
+ * - `requireApproval`: at most 100 entries, each 1–256 characters (R6.1)
+ *
+ * @param spec - The workflow module specification to validate.
+ * @returns The validated specification (unchanged).
+ * @throws {ValidationError} If any argument is invalid.
+ */
+export declare function defineDataWorkflow(spec: DataWorkflowModule): DataWorkflowModule;
+//# sourceMappingURL=define-data-workflow.d.ts.map

package/dist/authoring/define-data-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-data-workflow.d.ts","sourceRoot":"","sources":["../../src/authoring/define-data-workflow.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAWrD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,kBAAkB,CAiE/E"}

package/dist/authoring/define-data-workflow.js

@@ -0,0 +1,93 @@
+/**
+ * `defineDataWorkflow` factory — the core code-first authoring entry point.
+ *
+ * Validates the module specification synchronously using zod and throws a
+ * `ValidationError` naming the invalid argument on failure.
+ */
+import { z } from 'zod';
+import { ValidationError } from '../errors/index.js';
+/**
+ * Zod schema for the `requireApproval` array.
+ * Each entry is a non-empty string of 1–256 characters, with at most 100 entries.
+ */
+const requireApprovalSchema = z
+    .array(z.string().min(1).max(256))
+    .max(100)
+    .optional();
+/**
+ * Validates a `DataWorkflowModule` specification and returns it unchanged.
+ *
+ * Throws `ValidationError` (from `@loxtep/sdk/errors`) with a `field_errors`
+ * entry naming the invalid argument when validation fails.
+ *
+ * Validation rules:
+ * - `name`: 1–64 characters (R3.1, R3.8)
+ * - `triggers`: at least 1 and at most 10 entries (R3.1, R3.8)
+ * - `requireApproval`: at most 100 entries, each 1–256 characters (R6.1)
+ *
+ * @param spec - The workflow module specification to validate.
+ * @returns The validated specification (unchanged).
+ * @throws {ValidationError} If any argument is invalid.
+ */
+export function defineDataWorkflow(spec) {
+    const errors = [];
+    // Validate name (1–64 characters)
+    if (typeof spec.name !== 'string' || spec.name.length < 1 || spec.name.length > 64) {
+        errors.push({
+            field: 'name',
+            message: `name must be between 1 and 64 characters, got ${typeof spec.name === 'string' ? spec.name.length : typeof spec.name}`,
+        });
+    }
+    // Validate triggers (1–10)
+    if (!Array.isArray(spec.triggers) || spec.triggers.length < 1 || spec.triggers.length > 10) {
+        const count = Array.isArray(spec.triggers) ? spec.triggers.length : 0;
+        errors.push({
+            field: 'triggers',
+            message: `triggers must contain between 1 and 10 entries, got ${count}`,
+        });
+    }
+    // Validate requireApproval (≤100 entries, each 1–256 chars)
+    if (spec.requireApproval !== undefined) {
+        const result = requireApprovalSchema.safeParse(spec.requireApproval);
+        if (!result.success) {
+            const zodIssues = result.error.issues;
+            // Provide a targeted message based on the zod failure
+            const issue = zodIssues[0];
+            if (issue) {
+                if (issue.code === 'too_big' && issue.path.length === 0) {
+                    errors.push({
+                        field: 'requireApproval',
+                        message: `requireApproval must contain at most 100 entries, got ${spec.requireApproval.length}`,
+                    });
+                }
+                else if (issue.code === 'too_small' && issue.path.length > 0) {
+                    const idx = String(issue.path[0]);
+                    errors.push({
+                        field: 'requireApproval',
+                        message: `requireApproval[${idx}] must be between 1 and 256 characters`,
+                    });
+                }
+                else if (issue.code === 'too_big' && issue.path.length > 0) {
+                    const idx = issue.path[0];
+                    const idxStr = String(idx);
+                    errors.push({
+                        field: 'requireApproval',
+                        message: `requireApproval[${idxStr}] must be between 1 and 256 characters, got ${spec.requireApproval[idx]?.length}`,
+                    });
+                }
+                else {
+                    errors.push({
+                        field: 'requireApproval',
+                        message: `requireApproval is invalid: ${issue.message}`,
+                    });
+                }
+            }
+        }
+    }
+    if (errors.length > 0) {
+        const message = errors.map((e) => `${e.field}: ${e.message}`).join('; ');
+        throw new ValidationError(`Invalid defineDataWorkflow specification: ${message}`, errors);
+    }
+    return spec;
+}
+//# sourceMappingURL=define-data-workflow.js.map

package/dist/authoring/define-data-workflow.js.map

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

package/dist/authoring/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Code-first data workflow authoring surface.
+ *
+ * Entry points:
+ * - `defineDataWorkflow` — validates and returns a `DataWorkflowModule` spec
+ * - `on` — trigger builders (`queueEvent`, `connectorEvent`, `schedule`, `webhook`)
+ * - `createToolbox` — deterministic typed platform calls (no model in the loop)
+ * - `agent` — agentic operation entry point with scope enforcement and action trace
+ */
+export { defineDataWorkflow } from './define-data-workflow.js';
+export { on } from './triggers.js';
+export { createToolbox, ToolboxOperationError } from './toolbox.js';
+export { agent, validateAgentOptions, computeReachableScope, enforceAgentScope, createScopeGuardedToolbox, ActionTrace, AgentScopeError, } from './agent.js';
+export type { DataWorkflowModule, TriggerSpec, QueueRef, ConnectorRef, HandlerContext, ApprovalNodeSpec, AgentNodeSpec, } from './types.js';
+export { compileModule, computeRemovalSet } from './compiler.js';
+export type { GraphPatchOp, ResourceRef, CompiledWorkflow, } from './compiler.js';
+export type { Toolbox, ToolboxDataProducts, ToolboxQueues, ToolboxConnections, ToolboxWorkflows, CreateToolboxOptions, DataProductRef, WorkflowRef, WriteResult, QueryRows, } from './toolbox.js';
+export type { SkillRef, AgentOptions, ActionOutcome, ActionTraceEntry, AgentResult, AgentExecutionContext, } from './agent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/authoring/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/authoring/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAE,MAAM,eAAe,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EACL,KAAK,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,yBAAyB,EACzB,WAAW,EACX,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,kBAAkB,EAClB,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACjE,YAAY,EACV,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,OAAO,EACP,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,WAAW,EACX,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/authoring/index.js

@@ -0,0 +1,15 @@
+/**
+ * Code-first data workflow authoring surface.
+ *
+ * Entry points:
+ * - `defineDataWorkflow` — validates and returns a `DataWorkflowModule` spec
+ * - `on` — trigger builders (`queueEvent`, `connectorEvent`, `schedule`, `webhook`)
+ * - `createToolbox` — deterministic typed platform calls (no model in the loop)
+ * - `agent` — agentic operation entry point with scope enforcement and action trace
+ */
+export { defineDataWorkflow } from './define-data-workflow.js';
+export { on } from './triggers.js';
+export { createToolbox, ToolboxOperationError } from './toolbox.js';
+export { agent, validateAgentOptions, computeReachableScope, enforceAgentScope, createScopeGuardedToolbox, ActionTrace, AgentScopeError, } from './agent.js';
+export { compileModule, computeRemovalSet } from './compiler.js';
+//# sourceMappingURL=index.js.map

package/dist/authoring/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/authoring/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAE,MAAM,eAAe,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACpE,OAAO,EACL,KAAK,EACL,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,yBAAyB,EACzB,WAAW,EACX,eAAe,GAChB,MAAM,YAAY,CAAC;AAUpB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/authoring/toolbox.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Deterministic `toolbox` namespace — direct, typed platform calls with no model
+ * in the loop (R4.1, R4.7).
+ *
+ * Each method is a thin wrapper over the corresponding `LoxtepClient` namespace
+ * method. On success, it returns a typed result. On failure, it throws a
+ * `ToolboxOperationError` identifying the failed operation — it never falls back
+ * to a model.
+ */
+import type { LoxtepClient } from '../client/loxtep-client.js';
+import type { DataProduct, DataProductQueryResult } from '../client/data-products-types.js';
+import type { Connection, ConnectionTestResult } from '../client/connection-types.js';
+import type { Flow } from '../client/flow-types.js';
+import type { WorkflowGraph } from '../client/workflows-types.js';
+import type { QueueRef } from './types.js';
+import { LoxtepError } from '../errors/base.js';
+/** Result of a data product write operation. */
+export interface WriteResult {
+    /** Whether the write succeeded. */
+    success: true;
+    /** Number of events written. */
+    events_written: number;
+}
+/** Rows returned from a data product query. */
+export interface QueryRows {
+    items: Record<string, unknown>[];
+    metadata: DataProductQueryResult['metadata'];
+}
+/**
+ * Error thrown when a deterministic toolbox operation fails.
+ * Identifies the failed operation and namespace so the caller can
+ * distinguish it from other errors.
+ *
+ * Per R4.7 — the SDK never falls back to a model on failure.
+ */
+export declare class ToolboxOperationError extends LoxtepError {
+    /** The toolbox namespace where the failure occurred (e.g. 'dataProducts'). */
+    readonly namespace: string;
+    /** The operation that failed (e.g. 'write', 'query', 'list'). */
+    readonly operation: string;
+    constructor(namespace: string, operation: string, message: string, cause?: unknown);
+}
+/** Typed reference to a data product from the Generated_SDK_Artifact. */
+export interface DataProductRef {
+    id: string;
+    name: string;
+}
+/** Typed reference to a workflow from the Generated_SDK_Artifact. */
+export interface WorkflowRef {
+    id: string;
+    name: string;
+}
+export type { QueueRef, ConnectorRef } from './types.js';
+/**
+ * Data products toolbox — deterministic operations on data products.
+ */
+export interface ToolboxDataProducts {
+    /** Write an event to a data product's stream queue. */
+    write(ref: DataProductRef, event: unknown): Promise<WriteResult>;
+    /** Execute a SQL query against a data product. */
+    query(ref: DataProductRef, sql: string): Promise<QueryRows>;
+    /** Get a data product by reference. */
+    get(ref: DataProductRef): Promise<DataProduct>;
+    /** List data products (optionally filtered by domain). */
+    list(filters?: {
+        domain_id?: string;
+    }): Promise<DataProduct[]>;
+}
+/**
+ * Queues toolbox — deterministic operations on queues.
+ */
+export interface ToolboxQueues {
+    /** Write an event to a queue. */
+    write(ref: QueueRef, event: unknown): Promise<void>;
+    /** Get queue metadata. */
+    getMetadata(ref: QueueRef): Promise<{
+        queue_name: string;
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * Connections toolbox — deterministic operations on connections.
+ */
+export interface ToolboxConnections {
+    /** List connections for the project. */
+    list(): Promise<Connection[]>;
+    /** Get a specific connection. */
+    get(connectionId: string): Promise<Connection>;
+    /** Test a connection. */
+    test(connectionId: string): Promise<ConnectionTestResult>;
+}
+/**
+ * Workflows toolbox — deterministic operations on workflows.
+ */
+export interface ToolboxWorkflows {
+    /** List workflows for the project. */
+    list(): Promise<Flow[]>;
+    /** Get a workflow's graph. */
+    getGraph(ref: WorkflowRef): Promise<WorkflowGraph>;
+}
+/**
+ * The deterministic Toolbox namespace — thin typed wrappers over
+ * `LoxtepClient` namespaces. Each method returns typed results or throws a
+ * `ToolboxOperationError`. No model is ever invoked.
+ */
+export interface Toolbox {
+    dataProducts: ToolboxDataProducts;
+    queues: ToolboxQueues;
+    connections: ToolboxConnections;
+    workflows: ToolboxWorkflows;
+}
+/**
+ * Options for creating a toolbox.
+ */
+export interface CreateToolboxOptions {
+    /** The LoxtepClient instance to use for platform calls. */
+    client: LoxtepClient;
+    /** The project ID (used for project-scoped operations). */
+    projectId: string;
+}
+/**
+ * Create a `Toolbox` — deterministic, typed platform operations with no model
+ * in the loop.
+ *
+ * On success each method returns a typed result. On failure, a
+ * `ToolboxOperationError` is thrown identifying the failed operation.
+ * The toolbox never falls back to an AI model.
+ *
+ * @param options - Client and project configuration.
+ * @returns A `Toolbox` instance.
+ */
+export declare function createToolbox(options: CreateToolboxOptions): Toolbox;
+//# sourceMappingURL=toolbox.d.ts.map

package/dist/authoring/toolbox.d.ts.map

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