@hexabot-ai/agentic 3.0.1-alpha.0

package/LICENSE.md

@@ -0,0 +1,120 @@
+# Fair Core License, Version 1.0, ALv2 Future License
+
+## Abbreviation
+
+FCL-1.0-ALv2
+
+## Notice
+
+Copyright 2025 Hexastack
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Limitations,
+Patents, Redistribution and Trademark clauses below, we hereby grant you the
+right to use, copy, modify, create derivative works, publicly perform, publicly
+display and redistribute the Software for any Permitted Purpose identified
+below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Limitations
+
+You must not move, change, disable, or circumvent the license key functionality
+in the Software; or modify any portion of the Software protected by the license
+key to:
+
+1. enable access to the protected functionality without a valid license key; or
+
+2. remove the protected functionality.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright or other proprietary notices provided in or with the
+Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+In the event the provision of this Disclaimer section is unenforceable under
+applicable law, the licenses granted herein are void.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software,
+under the Apache License, Version 2.0, that is effective on the second
+anniversary of the date we make the Software available. On or after that date,
+you may use the Software under the Apache License, Version 2.0, in which case
+the following will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,231 @@
+# @hexabot-ai/agentic
+
+Typed runtime and YAML DSL for orchestrating multi-step AI/automation workflows. The package combines JSONata-powered expressions, schema validation, and a resumable runner so you can wire LLMs, tools, and human-in-the-loop pauses with reliable execution controls.
+
+## Highlights
+- Declarative workflow DSL in YAML or JS objects with JSONata expressions (prefixed by `=`) and clear scopes (`$input`, `$context`, `$output`, `$iteration`, `$accumulator`).
+- Type-safe actions built with `defineAction`, Zod-validated IO, and merged settings (timeouts, retries, plus action-specific options) inherited from workflow defaults.
+- Resumable execution via `WorkflowRunner` and `context.workflow.suspend`, plus snapshots for persistence and replay.
+- Flow primitives: sequential `do`, `parallel` blocks (`wait_all`/`wait_any`), `conditional` branches, and two loop variants: `loop.type: for_each` (iterables) and `loop.type: while` (pre-check condition).
+- Event emitter hooks for observability (`hook:workflow:start|finish|failure|suspended`, `hook:step:start|success|error|suspended|skipped`).
+
+## Installation
+
+```bash
+pnpm add @hexabot-ai/agentic
+# or
+npm install @hexabot-ai/agentic
+```
+
+Requires Node.js >= 20.18.1.
+
+The package ships both ESM (`import`) and CommonJS (`require`) entrypoints plus browser-safe internals, so you can run workflows in Node.js or bundle them for the client.
+
+## DSL essentials
+
+A workflow is a single YAML (or object) that declares inputs, context, defaults, definitions, control-flow, and outputs. The full annotated reference lives in `./DSL.md` and `examples/full/workflow.yml`. The important pieces:
+
+- `inputs.schema`: JSON-schema-like fields validated at runtime.
+- `context`: read-only values injected by the host (including any long-term state) and exposed to expressions.
+- `defaults.settings`: inherited by every task (timeouts, retries, and action-specific settings).
+- `defs`: required root registry for all definitions.
+- `defs.<name>` with `kind: task`: executable task defs with `action` and optional `inputs`, `settings`, `bindings`, `description`.
+- `defs.<name>` with `kind != task`: binding defs; `settings` is required (use `{}` when empty), with optional `action`, `bindings`, `description`.
+- `flow[].do`: must reference a `defs.<name>` entry where `kind: task`.
+- `defs.<name>.bindings`: optional kind-based refs on any def (`<kind>: [<defName>...]` for `multiple: true`, `<kind>: <defName>` for `multiple: false`).
+- `flow`: ordered list of steps combining `do`, `parallel`, `conditional`, `loop`.
+- `outputs`: expressions evaluated after the flow finishes.
+- `loop`: must declare `type` (`for_each` or `while`). Legacy loops without `type` are invalid.
+
+Task results are stored automatically under `$output.<task>` for downstream expressions.
+
+When workflows use defs with bindings, pass `bindingKinds` to `Workflow.fromYaml` / `Workflow.fromDefinition`. Each kind descriptor supports `{ schema, multiple, supportedBindings?, actionPolicy? }`.
+
+Binding validation is recursive and enforces cardinality, reference existence, kind matching, duplicate references, cycle detection, and allowlists:
+- if a def has `action`, allowlist comes from `actions[action].supportedBindings`.
+- otherwise allowlist comes from `bindingKinds[def.kind].supportedBindings`.
+- when `actions` are provided at compile time, defs declaring `action` must resolve.
+
+At runtime, mounted bindings follow kind cardinality:
+- `multiple: true` kinds mount as `{ [defName]: { settings, action?, bindings? } }`.
+- `multiple: false` kinds mount as `{ settings, action?, bindings? }`.
+
+Any string starting with `=` is parsed as JSONata; everything else is literal. Expressions receive `{ input, context, output, iteration, accumulator }` as scope; `$context` resolves to your workflow context state.
+
+## Defining actions
+
+Actions wrap your IO or model calls. `defineAction` enforces schemas and merges settings.
+
+```ts
+import { defineAction, Settings, BaseWorkflowContext } from '@hexabot-ai/agentic';
+import type { InferWorkflowBindings } from '@hexabot-ai/agentic';
+import { z } from 'zod';
+
+class AppContext extends BaseWorkflowContext<{ user_id: string }> {
+  log(message: string, payload?: unknown) {
+    console.log(message, payload);
+  }
+}
+
+const bindingKinds = {
+  tools: {
+    // For non-task kinds, schema validates the "settings" payload.
+    schema: z.record(z.string(), z.unknown()),
+    multiple: true,
+    actionPolicy: 'required' as const,
+    supportedBindings: ['tools'] as const,
+  },
+};
+type AppBindings = InferWorkflowBindings<typeof bindingKinds>;
+
+export const call_api = defineAction<
+  { id: string },
+  { body: string },
+  AppContext,
+  Settings,
+  AppBindings
+>({
+  name: 'call_api', // must match defs.<task>.action
+  description: 'Fetches data from an API',
+  inputSchema: z.object({ id: z.string() }),
+  outputSchema: z.object({ body: z.string() }),
+  execute: async ({ input, context, settings, bindings }) => {
+    context.log('calling api', {
+      id: input.id,
+      timeout: settings.timeout_ms,
+      tools: bindings.tools ? Object.keys(bindings.tools) : [],
+    });
+    return { body: `result for ${input.id}` };
+  },
+});
+```
+
+Settings are parsed and merged with workflow defaults before `execute` runs; retries and timeout wrappers are applied automatically. Awaiting `context.workflow.suspend(...)` pauses the workflow until `resume` is called.
+
+## Running a workflow from YAML
+
+```ts
+import { Workflow, WorkflowEventEmitter, BaseWorkflowContext } from '@hexabot-ai/agentic';
+import fs from 'node:fs';
+
+const yamlSource = fs.readFileSync('workflow.yml', 'utf8');
+const actions = { call_api }; // keys are action names referenced by defs.*.action
+
+class AppContext extends BaseWorkflowContext<{ user_id: string; thread_id: string }> {}
+
+const workflow = Workflow.fromYaml(yamlSource, { actions });
+
+const emitter = new WorkflowEventEmitter();
+emitter.on('hook:step:start', ({ step }) => console.log('start', step.id));
+
+const runner = await workflow.buildAsyncRunner();
+const context = new AppContext(
+  { user_id: 'user-1', thread_id: 'thread-1' },
+  emitter,
+);
+const startResult = await runner.start({
+  inputData: { id: '123' },
+  context,
+});
+
+if (startResult.status === 'finished') {
+  console.log('output', startResult.output);
+} else if (startResult.status === 'suspended') {
+  // persist startResult.snapshot and prompt the user; resume later:
+  const resumeResult = await runner.resume({ resumeData: { reply: 'go' } });
+  console.log(resumeResult.status, resumeResult.output);
+}
+```
+
+You can also skip YAML and use `Workflow.fromDefinition` with a typed object that matches `WorkflowDefinition`.
+Attach an event emitter to your workflow context (via the constructor or by setting `context.eventEmitter`); it accepts any object with `emit` and `on` methods. `WorkflowEventEmitter` is a small, dependency-free helper with typed payloads (`WorkflowEventEmitterLike` describes the shape).
+
+If your YAML declares `defs.*.bindings`, pass the same `bindingKinds` registry:
+
+```ts
+const workflow = Workflow.fromYaml(yamlSource, {
+  actions,
+  bindingKinds,
+});
+```
+
+### Minimal YAML example
+
+```yaml
+inputs:
+  schema:
+    user_id:
+      type: string
+defs:
+  greet_user:
+    kind: task
+    action: call_api
+    inputs:
+      id: "=$input.user_id"
+flow:
+  - do: greet_user
+outputs:
+  reply: "='Hello ' & $output.greet_user.body"
+```
+
+## Custom JSONata functions
+
+You can inject additional JSONata functions when compiling a workflow:
+
+```ts
+const workflow = Workflow.fromYaml(yamlSource, {
+  actions,
+  jsonataFunctions: {
+    i18n: (text: string) => translate(text, 'fr'),
+    slugify: { implementation: (value: string) => value.toLowerCase(), signature: 's' },
+  },
+});
+```
+
+These helpers are registered on every expression and can be referenced from YAML, e.g. `text: "=$i18n('Bye bye')"` inside `defs.<task>.inputs`.
+
+## Suspension and human-in-the-loop
+
+Inside an action you can pause execution and surface metadata to the caller:
+
+```ts
+export const await_user = defineAction<unknown, { reply?: string }, AppContext, Settings>({
+  name: 'await_user',
+  execute: async ({ context }) => {
+    const resumeData = await context.workflow.suspend({
+      reason: 'awaiting_user',
+      data: { prompt: 'Please confirm' },
+    });
+    return { reply: (resumeData as { reply?: string })?.reply };
+  },
+});
+```
+
+`Workflow.run` throws an error with suspension details (`stepId`, `reason`, `data`) when this happens; `WorkflowRunner.start` instead returns `{ status: 'suspended', ... }` so hosts can persist state and resume later with `runner.resume`.
+
+## Events and observability
+
+`WorkflowRunner` can publish lifecycle hooks to any emitter-like object with `emit`/`on` (`WorkflowEventEmitterLike`); `WorkflowEventEmitter` is the built-in helper and mirrors these events:
+
+- `hook:workflow:start | finish | failure | suspended`
+- `hook:step:start | success | error | suspended | skipped`
+
+Attach listeners to stream logs, emit metrics, or capture snapshots for debugging.
+
+## Examples and scripts
+
+- Full DSL walkthrough and runnable demo: `packages/agentic/DSL.md`, `packages/agentic/examples/full/workflow.yml`, `packages/agentic/examples/full/workflow.ts`, with mock actions in `packages/agentic/examples/full/actions/*`.
+- Loop quickstart (`while` loop + suspend/resume): `packages/agentic/examples/loop/workflow.yml` and `packages/agentic/examples/loop/workflow.ts`.
+- Suspend/resume quickstart: `packages/agentic/examples/suspend-resume/workflow.yml` and `packages/agentic/examples/suspend-resume/workflow.ts` show pausing a run and resuming with reply data.
+- Run the demos with ts-node: `pnpm dlx ts-node packages/agentic/examples/full/workflow.ts`, `pnpm dlx ts-node packages/agentic/examples/loop/workflow.ts`, or `pnpm dlx ts-node packages/agentic/examples/suspend-resume/workflow.ts`.
+
+## Development
+
+From the repository root:
+
+```bash
+pnpm --filter @hexabot-ai/agentic build
+pnpm --filter @hexabot-ai/agentic test
+```
+
+The codebase is TypeScript-first and validated with Zod; expressions use JSONata under the hood.

package/dist/cjs/action/abstract-action.js

@@ -0,0 +1,141 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractAction = void 0;
+const zod_1 = require("zod");
+const dsl_types_1 = require("../dsl.types");
+const naming_1 = require("../utils/naming");
+const timeout_1 = require("../utils/timeout");
+const BASE_SETTINGS_KEYS = Object.keys(dsl_types_1.BaseSettingsSchema.shape);
+/**
+ * Base implementation that enforces schema-validated input/output.
+ */
+class AbstractAction {
+    /**
+     * Sets up core metadata and schemas for the action.
+     *
+     * @param metadata - Describes the action name, description, and schemas.
+     * @param options - Optional configuration or definition override.
+     */
+    constructor(metadata) {
+        if (metadata.settingsSchema instanceof zod_1.z.ZodObject) {
+            const actionSettingsKeys = Object.keys(metadata.settingsSchema.shape);
+            const overlappingKeys = actionSettingsKeys.filter((key) => BASE_SETTINGS_KEYS.includes(key));
+            if (overlappingKeys.length > 0) {
+                throw new Error(`settingsSchema cannot redefine base settings keys: ${overlappingKeys.join(', ')}`);
+            }
+        }
+        (0, naming_1.assertSnakeCaseName)(metadata.name, 'action');
+        this.name = metadata.name;
+        this.description = metadata.description;
+        this.inputSchema = metadata.inputSchema;
+        this.outputSchema = metadata.outputSchema;
+        this.settingSchema = metadata.settingsSchema;
+        this.supportedBindings = metadata.supportedBindings ?? [];
+    }
+    /**
+     * Parses incoming payloads using the input schema.
+     *
+     * @param payload - Raw input received by the action.
+     * @returns Validated input typed as `I`.
+     */
+    parseInput(payload) {
+        return this.inputSchema.parse(payload);
+    }
+    /**
+     * Validates and returns the raw action output.
+     *
+     * @param payload - Raw output produced by {@link execute}.
+     * @returns Output typed as `O` after schema validation.
+     */
+    parseOutput(payload) {
+        return this.outputSchema.parse(payload);
+    }
+    /**
+     * Executes the action with retry, timeout, and schema safety.
+     *
+     * @param payload - Raw input being provided to the action.
+     * @param context - Workflow context used during execution.
+     * @returns Validated output produced by the action.
+     * @throws Error when retries are exhausted or validation fails.
+     */
+    parseSettings(payload) {
+        const settings = zod_1.z
+            .intersection(dsl_types_1.BaseSettingsSchema, this.settingSchema)
+            .parse(payload ?? {});
+        return (settings ?? {});
+    }
+    async run(payload, context, settings, bindings) {
+        const input = this.parseInput(payload);
+        const parsedSettings = this.parseSettings(settings);
+        const parsedBindings = (bindings ?? {});
+        this.assertSupportedBindings(parsedBindings);
+        const timeoutMs = parsedSettings.timeout_ms ?? 0;
+        const retrySettings = parsedSettings.retries ?? {
+            enabled: false,
+            max_attempts: 1,
+            backoff_ms: 0,
+            max_delay_ms: 0,
+            jitter: 0,
+            multiplier: 1,
+        };
+        const retriesEnabled = retrySettings.enabled ?? true;
+        const maxAttempts = retriesEnabled ? retrySettings.max_attempts : 1;
+        let attempt = 0;
+        let currentDelay = retrySettings.backoff_ms ?? 0;
+        const maxDelayMs = retrySettings.max_delay_ms;
+        const jitter = retrySettings.jitter;
+        const multiplier = retrySettings.multiplier;
+        while (attempt < maxAttempts) {
+            try {
+                const result = await (0, timeout_1.withTimeout)(this.execute({
+                    input,
+                    context,
+                    settings: parsedSettings,
+                    bindings: parsedBindings,
+                }), timeoutMs);
+                return this.parseOutput(result);
+            }
+            catch (error) {
+                attempt += 1;
+                if (attempt >= maxAttempts) {
+                    throw error;
+                }
+                let delay = currentDelay;
+                if (maxDelayMs > 0) {
+                    delay = Math.min(delay, maxDelayMs);
+                }
+                if (delay > 0) {
+                    const jitterFactor = jitter > 0 ? 1 + (Math.random() * 2 - 1) * jitter : 1;
+                    const jitteredDelay = Math.max(0, Math.round(delay * jitterFactor));
+                    if (jitteredDelay > 0) {
+                        await (0, timeout_1.sleep)(jitteredDelay);
+                    }
+                }
+                const nextDelay = currentDelay * multiplier;
+                currentDelay =
+                    maxDelayMs > 0 ? Math.min(nextDelay, maxDelayMs) : nextDelay;
+            }
+        }
+        throw new Error('Action failed after exhausting retry attempts.');
+    }
+    assertSupportedBindings(bindings) {
+        const bindingKinds = Object.keys((bindings ?? {}));
+        if (bindingKinds.length === 0) {
+            return;
+        }
+        const unsupportedKinds = bindingKinds.filter((bindingKind) => !this.supportedBindings.includes(bindingKind));
+        if (unsupportedKinds.length === 0) {
+            return;
+        }
+        const supported = this.supportedBindings.length > 0
+            ? this.supportedBindings.join(', ')
+            : '<none>';
+        throw new Error(`Action "${this.name}" does not support binding kind(s): ${unsupportedKinds.join(', ')}. Supported binding kinds: ${supported}.`);
+    }
+}
+exports.AbstractAction = AbstractAction;

package/dist/cjs/action/action.js

@@ -0,0 +1,47 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineAction = defineAction;
+const zod_1 = require("zod");
+const abstract_action_1 = require("./abstract-action");
+/**
+ * Builds an {@link AbstractAction} subclass from simple configuration.
+ *
+ * @param params - Action definition containing metadata and runtime logic.
+ * @returns Instantiated action ready to be used by a workflow.
+ * @typeParam I - Action input type.
+ * @typeParam O - Action output type.
+ * @typeParam Ctx - Workflow context type.
+ */
+function defineAction(params) {
+    const defaultSettingsSchema = zod_1.z.any();
+    const defaultInputSchema = zod_1.z.any();
+    const defaultOutputSchema = zod_1.z.any();
+    class FnAction extends abstract_action_1.AbstractAction {
+        constructor() {
+            const metadata = {
+                name: params.name,
+                description: params.description ?? '',
+                inputSchema: params.inputSchema ?? defaultInputSchema,
+                outputSchema: params.outputSchema ?? defaultOutputSchema,
+                settingsSchema: params.settingSchema ?? defaultSettingsSchema,
+                supportedBindings: params.supportedBindings,
+            };
+            super(metadata);
+        }
+        /**
+         * Delegates to the user supplied execute callback.
+         *
+         * @param args - Action execution arguments supplied by the runner.
+         * @returns Result of the user callback as a promise.
+         */
+        async execute(args) {
+            return await Promise.resolve(params.execute(args));
+        }
+    }
+    return new FnAction();
+}

package/dist/cjs/action/action.types.js

@@ -0,0 +1,7 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });