@hexabot-ai/agentic 3.0.1-alpha.0

package/examples/full/actions/get-user-profile.ts

@@ -0,0 +1,72 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import { SettingsSchema } from '../../../src/dsl.types';
+import type { ExampleContext } from '../context';
+
+const stakeholderSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+  role: z.string(),
+});
+const inputSchema = z.object({
+  user_id: z.string(),
+  include_history: z.boolean().optional(),
+});
+const outputSchema = z.object({
+  profile: z.object({
+    id: z.string(),
+    name: z.string(),
+    company: z.string(),
+    persona: z.string(),
+    stakeholders: z.array(stakeholderSchema),
+  }),
+  recent_cases: z.array(z.object({ id: z.string(), subject: z.string() })),
+});
+const settingsSchema = SettingsSchema;
+
+type GetUserProfileInput = z.infer<typeof inputSchema>;
+type GetUserProfileOutput = z.infer<typeof outputSchema>;
+type GetUserProfileSettings = z.infer<typeof settingsSchema>;
+
+export const getUserProfile = defineAction<
+  GetUserProfileInput,
+  GetUserProfileOutput,
+  ExampleContext,
+  GetUserProfileSettings
+>({
+  name: 'get_user_profile',
+  description:
+    'Returns a mocked CRM profile with a couple of stakeholders and prior cases.',
+  inputSchema,
+  outputSchema,
+  settingSchema: settingsSchema,
+  execute: async ({ input, context }) => {
+    const profile = {
+      id: input.user_id,
+      name: 'Ada Lovelace',
+      company: 'Analytical Engines Inc.',
+      persona: 'CTO',
+      stakeholders: [
+        { name: 'Mia Ops', email: 'mia.ops@example.com', role: 'operations' },
+        { name: 'Cal CTO', email: 'cal.cto@example.com', role: 'technology' },
+      ],
+    };
+    const recent_cases = input.include_history
+      ? [
+          { id: 'case-100', subject: 'Renewal follow-up' },
+          { id: 'case-101', subject: 'Product feedback' },
+        ]
+      : [];
+
+    context.log('Fetched profile', { user_id: input.user_id });
+
+    return { profile, recent_cases };
+  },
+});

package/examples/full/actions/index.ts

@@ -0,0 +1,33 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { Action, Settings } from '../../../src';
+import type { ExampleContext } from '../context';
+
+import { awaitUserInput } from './await-user-input';
+import { callLlm } from './call-llm';
+import { createTicket } from './create-ticket';
+import { decisionRouter } from './decision-router';
+import { getCalendarEvents } from './get-calendar-events';
+import { getUserProfile } from './get-user-profile';
+import { queryMemory } from './query-memory';
+import { searchWeb } from './search-web';
+import { sendEmail } from './send-email';
+
+export const exampleActions: Record<
+  string,
+  Action<unknown, unknown, ExampleContext, Settings>
+> = {
+  call_llm: callLlm,
+  get_user_profile: getUserProfile,
+  search_web: searchWeb,
+  query_memory: queryMemory,
+  get_calendar_events: getCalendarEvents,
+  await_user_input: awaitUserInput,
+  decision_router: decisionRouter,
+  create_ticket: createTicket,
+  send_email: sendEmail,
+};

package/examples/full/actions/query-memory.ts

@@ -0,0 +1,45 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import { SettingsSchema } from '../../../src/dsl.types';
+import type { ExampleContext } from '../context';
+
+const inputSchema = z.object({
+  thread_id: z.string().optional(),
+  user_id: z.string().optional(),
+});
+const outputSchema = z.object({
+  summary: z.string(),
+});
+const settingsSchema = SettingsSchema;
+
+type QueryMemoryInput = z.infer<typeof inputSchema>;
+type QueryMemoryOutput = z.infer<typeof outputSchema>;
+type QueryMemorySettings = z.infer<typeof settingsSchema>;
+
+export const queryMemory = defineAction<
+  QueryMemoryInput,
+  QueryMemoryOutput,
+  ExampleContext,
+  QueryMemorySettings
+>({
+  name: 'query_memory',
+  description: 'Returns a canned memory summary for the provided thread.',
+  inputSchema,
+  outputSchema,
+  settingSchema: settingsSchema,
+  execute: async ({ input, context }) => {
+    context.log('Fetching memory thread', {
+      thread_id: input.thread_id,
+      user_id: input.user_id,
+    });
+
+    return { summary: 'Previous discussion summarized for quick recall.' };
+  },
+});

package/examples/full/actions/search-web.ts

@@ -0,0 +1,53 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import { SettingsSchema } from '../../../src/dsl.types';
+import type { ExampleContext } from '../context';
+
+const inputSchema = z.object({
+  query: z.string(),
+  limit: z.number().int().positive().optional(),
+});
+const outputSchema = z.object({
+  links: z.array(z.string()),
+  snippets: z.array(z.string()),
+});
+const settingsSchema = SettingsSchema;
+
+type SearchWebInput = z.infer<typeof inputSchema>;
+type SearchWebOutput = z.infer<typeof outputSchema>;
+type SearchWebSettings = z.infer<typeof settingsSchema>;
+
+export const searchWeb = defineAction<
+  SearchWebInput,
+  SearchWebOutput,
+  ExampleContext,
+  SearchWebSettings
+>({
+  name: 'search_web',
+  description: 'Stubbed web search returning predictable links for the demo.',
+  inputSchema,
+  outputSchema,
+  settingSchema: settingsSchema,
+  execute: async ({ input, context }) => {
+    const limit = input.limit ?? 3;
+    context.log('Searching web', { query: input.query, limit });
+
+    const snippets = Array.from(
+      { length: limit },
+      (_, index) => `Result ${index + 1} about ${input.query}`,
+    );
+    const links = snippets.map(
+      (snippet, index) =>
+        `https://example.com/${index + 1}?q=${encodeURIComponent(input.query)}`,
+    );
+
+    return { links, snippets };
+  },
+});

package/examples/full/actions/send-email.ts

@@ -0,0 +1,50 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../../../src';
+import { SettingsSchema } from '../../../src/dsl.types';
+import type { ExampleContext } from '../context';
+
+const inputSchema = z.object({
+  to: z.string(),
+  subject: z.string(),
+  body: z.unknown(),
+  track_opens: z.boolean().optional(),
+});
+const outputSchema = z.object({
+  status: z.string(),
+  acknowledged: z.boolean().optional(),
+});
+const settingsSchema = SettingsSchema;
+
+type SendEmailInput = z.infer<typeof inputSchema>;
+type SendEmailOutput = z.infer<typeof outputSchema>;
+type SendEmailSettings = z.infer<typeof settingsSchema>;
+
+export const sendEmail = defineAction<
+  SendEmailInput,
+  SendEmailOutput,
+  ExampleContext,
+  SendEmailSettings
+>({
+  name: 'send_email',
+  description:
+    'Pretends to send an email and optionally marks acknowledgement.',
+  inputSchema,
+  outputSchema,
+  settingSchema: settingsSchema,
+  execute: async ({ input, context }) => {
+    const acknowledged =
+      input.subject.toLowerCase().includes('fyi') &&
+      input.to.toLowerCase().includes('ops');
+
+    context.log('Sent email', { to: input.to, subject: input.subject });
+
+    return { status: 'sent', acknowledged };
+  },
+});

package/examples/full/context.ts

@@ -0,0 +1,41 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  BaseWorkflowContext,
+  WorkflowEventEmitter,
+  type WorkflowEventEmitterLike,
+} from '../../src';
+
+export type ExampleContextState = {
+  user_id: string;
+  account_tier: string;
+  locale: string;
+  timezone: string;
+  channel: string;
+  thread_id: string;
+  full_transcript: string;
+  last_summary: string;
+  support_playbook: string;
+  product_brief: string;
+};
+
+export class ExampleContext extends BaseWorkflowContext<ExampleContextState> {
+  public eventEmitter: WorkflowEventEmitterLike<WorkflowEventEmitter>;
+
+  constructor(
+    state: ExampleContextState,
+    eventEmitter: WorkflowEventEmitterLike<WorkflowEventEmitter> = new WorkflowEventEmitter(),
+  ) {
+    super(state);
+    this.eventEmitter = eventEmitter;
+  }
+
+  log(message: string, payload?: unknown): void {
+    const suffix = payload === undefined ? '' : ` ${JSON.stringify(payload)}`;
+    console.log(`[workflow] ${message}${suffix}`);
+  }
+}

package/examples/full/workflow.ts

@@ -0,0 +1,75 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+import { Workflow, WorkflowEventEmitter } from '../../src';
+
+import { exampleActions } from './actions';
+import { ExampleContext } from './context';
+
+const workflowPath = path.join(__dirname, 'workflow.yml');
+
+async function main() {
+  const yamlSource = fs.readFileSync(workflowPath, 'utf8');
+  const workflow = Workflow.fromYaml(yamlSource, {
+    actions: exampleActions,
+  });
+  const emitter = new WorkflowEventEmitter();
+  const context = new ExampleContext(
+    {
+      user_id: 'user-123',
+      account_tier: 'pro',
+      locale: 'en-US',
+      timezone: 'America/Los_Angeles',
+      channel: 'email',
+      thread_id: 'thread-123',
+      full_transcript: 'Conversation so far with the user.',
+      last_summary: 'Previous summary of the issue.',
+      support_playbook: 'Support runbook v1.2',
+      product_brief: 'Launch messaging and positioning.',
+    },
+    emitter,
+  );
+  emitter.on('hook:step:start', ({ step }) =>
+    context.log(`hook:step:start:${step.name}`),
+  );
+  emitter.on('hook:step:success', ({ step }) =>
+    context.log(`hook:step:success:${step.name}`),
+  );
+  emitter.on('hook:workflow:finish', ({ output }) =>
+    context.log('hook:workflow:finish', output),
+  );
+  const runner = await workflow.buildAsyncRunner();
+  const inputData = {
+    query: 'We are seeing API errors after deploying billing changes.',
+    user_email: 'customer@example.com',
+    priority: 'normal',
+    attachments: [],
+  };
+  const result = await runner.start({ inputData, context });
+
+  if (result.status === 'finished') {
+    console.log('Final workflow outputs:', result.output);
+
+    return;
+  }
+
+  if (result.status === 'suspended') {
+    console.log(
+      `Workflow suspended at step ${result.step.id} for reason "${result.reason}"`,
+      result.data,
+    );
+
+    return;
+  }
+
+  console.error('Workflow failed:', result.error);
+}
+
+// pnpm dlx ts-node packages/agentic/examples/full/workflow.ts
+void main();