@sensigo/realm 0.1.0

package/README.md

@@ -0,0 +1,150 @@
+# @sensigo/realm
+
+`@sensigo/realm` — the Realm workflow execution engine. Use this package to load, register, and execute YAML-defined workflows programmatically, or to build custom service adapters and step handlers.
+
+## Installation
+
+```
+npm install @sensigo/realm
+```
+
+## Usage — Execute a Workflow
+
+Load a workflow definition and drive it step by step. Each `executeStep` call advances the run and returns a `ResponseEnvelope` with the current state and what comes next.
+
+```ts
+import { loadWorkflowFromFile, JsonFileStore, executeStep } from '@sensigo/realm';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const definition = loadWorkflowFromFile(path.join(__dirname, 'my-workflow/workflow.yaml'));
+
+const store = new JsonFileStore(); // defaults to ~/.realm/runs/
+const run = await store.create({
+  workflowId: definition.id,
+  workflowVersion: definition.version,
+  params: { input: 'hello' },
+});
+
+const response = await executeStep(store, definition, {
+  runId: run.id,
+  command: 'my_step',
+  input: { answer: 'done' },
+  dispatcher: async (_stepName, stepInput) => stepInput, // replace with real agent/handler
+});
+
+console.log(response.status);
+// response.next_actions[0] carries the next step to execute — repeat until next_actions is empty
+```
+
+## Usage — Custom Service Adapter
+
+Implement `ServiceAdapter` to connect a workflow step to any external API, then register it with `ExtensionRegistry` before executing.
+
+```ts
+import {
+  ExtensionRegistry,
+  executeStep,
+  type ServiceAdapter,
+  type ServiceResponse,
+} from '@sensigo/realm';
+
+const myAdapter: ServiceAdapter = {
+  id: 'my-api',
+  async fetch(operation, params, _config): Promise<ServiceResponse> {
+    const data = await callMyApi(operation, params);
+    return { status: 200, data };
+  },
+  async create(operation, params, _config): Promise<ServiceResponse> {
+    return this.fetch(operation, params, _config);
+  },
+  async update(operation, params, _config): Promise<ServiceResponse> {
+    return this.fetch(operation, params, _config);
+  },
+};
+
+const registry = new ExtensionRegistry();
+registry.register('adapter', 'my-adapter', myAdapter);
+
+// Pass registry to executeStep or executeChain:
+// await executeStep(store, definition, { ..., registry });
+```
+
+## API Reference
+
+### Engine
+
+| Symbol                | Notes                                                           |
+| --------------------- | --------------------------------------------------------------- |
+| `executeStep`         | Advance a run by one step. Returns `ResponseEnvelope`.          |
+| `executeChain`        | Auto-chain through auto steps until an agent step is reached.   |
+| `submitHumanResponse` | Resolve an open human gate.                                     |
+| `buildNextActions`    | Build `NextAction[]` for all currently eligible agent steps.    |
+| `findEligibleSteps`   | Return names of steps ready to execute given current run state. |
+| `propagateSkips`      | Propagate skip flags through dependent steps.                   |
+
+### Store
+
+| Symbol              | Notes                                                  |
+| ------------------- | ------------------------------------------------------ |
+| `JsonFileStore`     | File-backed `RunStore`. Defaults to `~/.realm/runs/`.  |
+| `JsonWorkflowStore` | File-backed store for registered workflow definitions. |
+
+### Workflow
+
+| Symbol                   | Notes                                                  |
+| ------------------------ | ------------------------------------------------------ |
+| `loadWorkflowFromFile`   | Synchronous. Parses `workflow.yaml` at the given path. |
+| `loadWorkflowFromString` | Parse a workflow from a raw YAML string.               |
+
+### Adapters
+
+| Symbol               |
+| -------------------- |
+| `FileSystemAdapter`  |
+| `GitHubAdapter`      |
+| `SlackAdapter`       |
+| `GenericHttpAdapter` |
+| `MockAdapter`        |
+
+### Registry
+
+| Symbol                  |
+| ----------------------- |
+| `ExtensionRegistry`     |
+| `createDefaultRegistry` |
+
+### Types
+
+| Symbol               |
+| -------------------- |
+| `WorkflowDefinition` |
+| `RunRecord`          |
+| `ResponseEnvelope`   |
+| `ServiceAdapter`     |
+| `ServiceResponse`    |
+| `RunStore`           |
+| `WorkflowError`      |
+
+### Processors
+
+| Symbol          |
+| --------------- |
+| `normalizeText` |
+| `computeHash`   |
+
+### Handler primitives
+
+| Symbol                 |
+| ---------------------- |
+| `resolveResource`      |
+| `walkField`            |
+| `partitionBySubstring` |
+| `countResults`         |
+| `compareStrings`       |
+
+## Full documentation
+
+Full documentation: https://github.com/sensigo-hq/realm

package/dist/adapters/adapter-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses the Retry-After HTTP header value into a delay in seconds.
+ * Handles both integer-seconds form (e.g. "30") and HTTP-date form
+ * (e.g. "Sat, 31 May 2026 12:00:00 GMT").
+ *
+ * Known limitation: clock skew between client and server is not corrected.
+ * Math.max(0, ...) prevents negative values when the date is in the past.
+ *
+ * @param raw  The raw header value from response.headers.get('Retry-After').
+ * @param fallback  Conservative default to use when the header is absent or unparseable.
+ */
+export declare function parseRetryAfterHeader(raw: string | null, fallback: number): number;
+export declare function parseRetryAfterHeader(raw: string | null, fallback?: undefined): number | undefined;
+//# sourceMappingURL=adapter-utils.d.ts.map

package/dist/adapters/adapter-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-utils.d.ts","sourceRoot":"","sources":["../../src/adapters/adapter-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;AACpF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC"}

package/dist/adapters/adapter-utils.js

@@ -0,0 +1,18 @@
+export function parseRetryAfterHeader(raw, fallback) {
+    if (raw !== null) {
+        // Integer-seconds form (e.g. "30"). parseInt handles potential decimal inputs
+        // from non-conformant servers (e.g. "30.5" → 30).
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n))
+            return Math.max(0, n);
+        // HTTP-date form (e.g. "Sat, 31 May 2026 12:00:00 GMT").
+        // Known limitation: clock skew between client and server is not corrected.
+        // Math.max(0, ...) prevents negative values when the date is in the past.
+        const date = new Date(raw);
+        if (Number.isFinite(date.getTime())) {
+            return Math.max(0, Math.floor((date.getTime() - Date.now()) / 1000));
+        }
+    }
+    return fallback;
+}
+//# sourceMappingURL=adapter-utils.js.map

package/dist/adapters/adapter-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-utils.js","sourceRoot":"","sources":["../../src/adapters/adapter-utils.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,qBAAqB,CAAC,GAAkB,EAAE,QAAiB;IACzE,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,8EAA8E;QAC9E,kDAAkD;QAClD,MAAM,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC5B,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9C,yDAAyD;QACzD,2EAA2E;QAC3E,0EAA0E;QAC1E,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YACpC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/adapters/airtable-adapter.d.ts

@@ -0,0 +1,51 @@
+import type { ServiceAdapter, ServiceResponse } from '../extensions/service-adapter.js';
+/**
+ * Configuration for AirtableAdapter.
+ *
+ * One adapter instance is scoped to a single Airtable base. For multi-base workflows,
+ * create one adapter instance per base.
+ */
+export interface AirtableAdapterConfig {
+    /**
+     * Personal Access Token (PAT). Required.
+     * Rate limit: 5 req/sec per base. On HTTP 429, wait 30 seconds before retrying.
+     * No Retry-After header is provided by Airtable.
+     */
+    api_key: string;
+    /**
+     * Airtable base ID. Format: /^app[a-zA-Z0-9]{14}$/.
+     * One adapter instance per base. Multi-base = two instances.
+     */
+    base_id: string;
+    /**
+     * Override the base URL for tests (replaces https://api.airtable.com).
+     * Trailing slash is stripped.
+     */
+    base_url?: string;
+}
+/**
+ * AirtableAdapter wraps the Airtable REST API.
+ *
+ * Supported operations:
+ *   fetch('get_record', { table, record_id })        — GET  /v0/{base}/{table}/{id}
+ *   fetch('list_records', { table, ...query })       — GET  /v0/{base}/{table}
+ *   create('create_record', { table, fields, ... })  — POST /v0/{base}/{table}
+ *   update('upsert_record', { table, fields, ... })  — POST /v0/{base}/{table} (upsert)
+ */
+export declare class AirtableAdapter implements ServiceAdapter {
+    readonly id: string;
+    readonly defaultRetryAfterSeconds = 30;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly baseId;
+    constructor(id: string, config: AirtableAdapterConfig);
+    private checkAborted;
+    private buildHeaders;
+    private buildUrl;
+    private executeRequest;
+    private throwHttpError;
+    fetch(operation: string, params: Record<string, unknown>, _config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+    create(operation: string, params: Record<string, unknown>, _config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+    update(operation: string, params: Record<string, unknown>, _config: Record<string, unknown>, signal?: AbortSignal): Promise<ServiceResponse>;
+}
+//# sourceMappingURL=airtable-adapter.d.ts.map

package/dist/adapters/airtable-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"airtable-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/airtable-adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAKxF;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AASD;;;;;;;;GAQG;AACH,qBAAa,eAAgB,YAAW,cAAc;IACpD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,wBAAwB,MAAM;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB;IAerD,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,QAAQ;YAQF,cAAc;YAyCd,cAAc;IAqFtB,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IA4HrB,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAwErB,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;CAqG5B"}

package/dist/adapters/airtable-adapter.js

@@ -0,0 +1,425 @@
+// AirtableAdapter — wraps the Airtable REST API for record-level operations.
+import { WorkflowError } from '../types/workflow-error.js';
+import { parseRetryAfterHeader } from './adapter-utils.js';
+const AIRTABLE_DEFAULT_BASE_URL = 'https://api.airtable.com';
+/**
+ * AirtableAdapter wraps the Airtable REST API.
+ *
+ * Supported operations:
+ *   fetch('get_record', { table, record_id })        — GET  /v0/{base}/{table}/{id}
+ *   fetch('list_records', { table, ...query })       — GET  /v0/{base}/{table}
+ *   create('create_record', { table, fields, ... })  — POST /v0/{base}/{table}
+ *   update('upsert_record', { table, fields, ... })  — POST /v0/{base}/{table} (upsert)
+ */
+export class AirtableAdapter {
+    id;
+    defaultRetryAfterSeconds = 30;
+    baseUrl;
+    apiKey;
+    baseId;
+    constructor(id, config) {
+        if (!config.api_key) {
+            throw new Error('AirtableAdapter: api_key must not be empty');
+        }
+        if (!/^app[a-zA-Z0-9]{14}$/.test(config.base_id)) {
+            throw new Error('AirtableAdapter: base_id must be a valid Airtable base ID (format: appXXXXXXXXXXXXXX)');
+        }
+        this.id = id;
+        this.apiKey = config.api_key;
+        this.baseId = config.base_id;
+        this.baseUrl = config.base_url?.replace(/\/$/, '') ?? AIRTABLE_DEFAULT_BASE_URL;
+    }
+    checkAborted(signal) {
+        if (signal?.aborted === true) {
+            throw new WorkflowError('Adapter request aborted', {
+                code: 'STEP_ABORTED',
+                category: 'ENGINE',
+                agentAction: 'report_to_user',
+                retryable: false,
+            });
+        }
+    }
+    buildHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+        };
+    }
+    buildUrl(table, recordId) {
+        let path = `/v0/${this.baseId}/${encodeURIComponent(table)}`;
+        if (recordId !== undefined) {
+            path += `/${encodeURIComponent(recordId)}`;
+        }
+        return new URL(path, this.baseUrl);
+    }
+    async executeRequest(url, method, body, signal) {
+        this.checkAborted(signal);
+        const hasBody = method !== 'GET' && body !== undefined;
+        const headers = {
+            ...this.buildHeaders(),
+            ...(hasBody ? { 'Content-Type': 'application/json' } : {}),
+        };
+        let response;
+        try {
+            response = await fetch(url.href, {
+                method,
+                headers,
+                ...(hasBody ? { body: JSON.stringify(body) } : {}),
+                signal: signal ?? null,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new WorkflowError('Adapter request aborted', {
+                    code: 'STEP_ABORTED',
+                    category: 'ENGINE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new WorkflowError(message, {
+                code: 'NETWORK_UNREACHABLE',
+                category: 'NETWORK',
+                agentAction: 'wait_for_human',
+                retryable: true,
+            });
+        }
+        return response;
+    }
+    async throwHttpError(response, operation) {
+        // Read body as text first — avoids "body already consumed" if JSON.parse fails.
+        const rawText = await response.text();
+        let body;
+        try {
+            body = JSON.parse(rawText);
+        }
+        catch {
+            body = rawText;
+        }
+        const status = response.status;
+        const baseDetails = { status, operation };
+        if (status === 401) {
+            throw new WorkflowError('Airtable authentication failed — check API key', {
+                code: 'SERVICE_AUTH_FAILED',
+                category: 'SERVICE',
+                agentAction: 'stop',
+                retryable: false,
+                details: baseDetails,
+            });
+        }
+        if (status === 403) {
+            throw new WorkflowError('Airtable: forbidden (HTTP 403)', {
+                code: 'SERVICE_HTTP_4XX',
+                category: 'SERVICE',
+                agentAction: 'stop',
+                retryable: false,
+                details: baseDetails,
+            });
+        }
+        if (status === 404) {
+            throw new WorkflowError('Airtable: record not found', {
+                code: 'SERVICE_NOT_FOUND',
+                category: 'SERVICE',
+                agentAction: 'provide_input',
+                retryable: false,
+                details: baseDetails,
+            });
+        }
+        if (status === 422) {
+            throw new WorkflowError('Airtable: unprocessable entity (HTTP 422)', {
+                code: 'SERVICE_HTTP_4XX',
+                category: 'SERVICE',
+                agentAction: 'stop',
+                retryable: false,
+                details: { ...baseDetails, body },
+            });
+        }
+        if (status === 429) {
+            const retryAfterFromHeader = parseRetryAfterHeader(response.headers.get('Retry-After'));
+            throw new WorkflowError('Rate limited by Airtable API', {
+                code: 'SERVICE_RATE_LIMITED',
+                category: 'SERVICE',
+                agentAction: 'wait_and_proceed',
+                retryable: true,
+                ...(retryAfterFromHeader !== undefined ? { retry_after: retryAfterFromHeader } : {}),
+                details: baseDetails,
+            });
+        }
+        if (status >= 500) {
+            throw new WorkflowError(`Airtable server error (HTTP ${status})`, {
+                code: 'SERVICE_HTTP_5XX',
+                category: 'SERVICE',
+                agentAction: 'report_to_user',
+                retryable: true,
+                details: baseDetails,
+            });
+        }
+        // 400 and other 4xx
+        throw new WorkflowError(`HTTP ${status}: ${response.statusText}`, {
+            code: 'SERVICE_HTTP_4XX',
+            category: 'SERVICE',
+            agentAction: 'stop',
+            retryable: false,
+            details: baseDetails,
+        });
+    }
+    async fetch(operation, params, _config, signal) {
+        if (operation === 'get_record') {
+            const table = params['table'];
+            const recordId = params['record_id'];
+            if (typeof table !== 'string' || table === '') {
+                throw new WorkflowError('AirtableAdapter: table param must be a non-empty string', {
+                    code: 'ADAPTER_VALIDATION_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'provide_input',
+                    retryable: false,
+                });
+            }
+            if (typeof recordId !== 'string' || recordId === '') {
+                throw new WorkflowError('AirtableAdapter: record_id param must be a non-empty string', {
+                    code: 'ADAPTER_VALIDATION_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'provide_input',
+                    retryable: false,
+                });
+            }
+            const url = this.buildUrl(table, recordId);
+            const response = await this.executeRequest(url, 'GET', undefined, signal);
+            if (!response.ok) {
+                await this.throwHttpError(response, 'get_record');
+            }
+            let parsed;
+            try {
+                parsed = await response.json();
+            }
+            catch {
+                throw new WorkflowError('AirtableAdapter: failed to parse response body', {
+                    code: 'SERVICE_RESPONSE_INVALID',
+                    category: 'SERVICE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            const data = parsed;
+            if (typeof data.id !== 'string' || data.id === '') {
+                throw new WorkflowError('AirtableAdapter: get_record response missing id field', {
+                    code: 'SERVICE_RESPONSE_INVALID',
+                    category: 'SERVICE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            return { status: response.status, data: parsed };
+        }
+        if (operation === 'list_records') {
+            const table = params['table'];
+            if (typeof table !== 'string' || table === '') {
+                throw new WorkflowError('AirtableAdapter: table param must be a non-empty string', {
+                    code: 'ADAPTER_VALIDATION_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'provide_input',
+                    retryable: false,
+                });
+            }
+            const url = this.buildUrl(table);
+            if (typeof params['filter_by_formula'] === 'string') {
+                url.searchParams.set('filterByFormula', params['filter_by_formula']);
+            }
+            if (typeof params['view'] === 'string') {
+                url.searchParams.set('view', params['view']);
+            }
+            if (typeof params['max_records'] === 'number') {
+                url.searchParams.set('maxRecords', String(params['max_records']));
+            }
+            if (Array.isArray(params['fields'])) {
+                for (const f of params['fields']) {
+                    url.searchParams.append('fields[]', String(f));
+                }
+            }
+            if (typeof params['offset'] === 'string') {
+                url.searchParams.set('offset', params['offset']);
+            }
+            const response = await this.executeRequest(url, 'GET', undefined, signal);
+            if (!response.ok) {
+                await this.throwHttpError(response, 'list_records');
+            }
+            let parsed;
+            try {
+                parsed = await response.json();
+            }
+            catch {
+                throw new WorkflowError('AirtableAdapter: failed to parse response body', {
+                    code: 'SERVICE_RESPONSE_INVALID',
+                    category: 'SERVICE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            const data = parsed;
+            if (!Array.isArray(data.records)) {
+                throw new WorkflowError('AirtableAdapter: list_records response missing records array', {
+                    code: 'SERVICE_RESPONSE_INVALID',
+                    category: 'SERVICE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            return { status: response.status, data: parsed };
+        }
+        throw new WorkflowError(`AirtableAdapter: unsupported fetch operation "${operation}"`, {
+            code: 'ADAPTER_OP_UNSUPPORTED',
+            category: 'ENGINE',
+            agentAction: 'report_to_user',
+            retryable: false,
+        });
+    }
+    async create(operation, params, _config, signal) {
+        if (operation === 'create_record') {
+            const table = params['table'];
+            const fields = params['fields'];
+            if (typeof table !== 'string' || table === '') {
+                throw new WorkflowError('AirtableAdapter: table param must be a non-empty string', {
+                    code: 'ADAPTER_VALIDATION_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'provide_input',
+                    retryable: false,
+                });
+            }
+            if (fields === undefined ||
+                fields === null ||
+                typeof fields !== 'object' ||
+                Array.isArray(fields)) {
+                throw new WorkflowError('AirtableAdapter: fields param must be a plain object', {
+                    code: 'ADAPTER_VALIDATION_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'provide_input',
+                    retryable: false,
+                });
+            }
+            const body = { fields };
+            if (params['typecast'] === true) {
+                body['typecast'] = true;
+            }
+            const url = this.buildUrl(table);
+            const response = await this.executeRequest(url, 'POST', body, signal);
+            if (!response.ok) {
+                await this.throwHttpError(response, 'create_record');
+            }
+            let parsed;
+            try {
+                parsed = await response.json();
+            }
+            catch {
+                throw new WorkflowError('AirtableAdapter: failed to parse response body', {
+                    code: 'SERVICE_RESPONSE_INVALID',
+                    category: 'SERVICE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            const data = parsed;
+            if (typeof data.id !== 'string' || data.id === '') {
+                throw new WorkflowError('AirtableAdapter: create_record response missing id field', {
+                    code: 'SERVICE_RESPONSE_INVALID',
+                    category: 'SERVICE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            return { status: response.status, data: parsed };
+        }
+        throw new WorkflowError(`AirtableAdapter: unsupported create operation "${operation}"`, {
+            code: 'ADAPTER_OP_UNSUPPORTED',
+            category: 'ENGINE',
+            agentAction: 'report_to_user',
+            retryable: false,
+        });
+    }
+    async update(operation, params, _config, signal) {
+        if (operation === 'upsert_record') {
+            const table = params['table'];
+            const fields = params['fields'];
+            const fieldsToMergeOn = params['fields_to_merge_on'];
+            if (typeof table !== 'string' || table === '') {
+                throw new WorkflowError('AirtableAdapter: table param must be a non-empty string', {
+                    code: 'ADAPTER_VALIDATION_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'provide_input',
+                    retryable: false,
+                });
+            }
+            if (fields === undefined ||
+                fields === null ||
+                typeof fields !== 'object' ||
+                Array.isArray(fields)) {
+                throw new WorkflowError('AirtableAdapter: fields param must be a plain object', {
+                    code: 'ADAPTER_VALIDATION_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'provide_input',
+                    retryable: false,
+                });
+            }
+            // Validate fields_to_merge_on: must be a non-empty array of non-empty strings
+            if (!Array.isArray(fieldsToMergeOn) || fieldsToMergeOn.length === 0) {
+                throw new WorkflowError('AirtableAdapter: fields_to_merge_on must be a non-empty array of non-empty strings', {
+                    code: 'ADAPTER_VALIDATION_FAILED',
+                    category: 'ENGINE',
+                    agentAction: 'provide_input',
+                    retryable: false,
+                });
+            }
+            for (const element of fieldsToMergeOn) {
+                if (typeof element !== 'string' || element === '') {
+                    throw new WorkflowError('AirtableAdapter: fields_to_merge_on must be a non-empty array of non-empty strings', {
+                        code: 'ADAPTER_VALIDATION_FAILED',
+                        category: 'ENGINE',
+                        agentAction: 'provide_input',
+                        retryable: false,
+                    });
+                }
+            }
+            const body = {
+                records: [{ fields }],
+                performUpsert: { fieldsToMergeOn },
+            };
+            if (params['typecast'] === true) {
+                body['typecast'] = true;
+            }
+            const url = this.buildUrl(table);
+            const response = await this.executeRequest(url, 'POST', body, signal);
+            if (!response.ok) {
+                await this.throwHttpError(response, 'upsert_record');
+            }
+            let parsed;
+            try {
+                parsed = await response.json();
+            }
+            catch {
+                throw new WorkflowError('AirtableAdapter: failed to parse response body', {
+                    code: 'SERVICE_RESPONSE_INVALID',
+                    category: 'SERVICE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            const data = parsed;
+            if (!Array.isArray(data.records)) {
+                throw new WorkflowError('AirtableAdapter: upsert_record response missing records array', {
+                    code: 'SERVICE_RESPONSE_INVALID',
+                    category: 'SERVICE',
+                    agentAction: 'report_to_user',
+                    retryable: false,
+                });
+            }
+            return { status: response.status, data: parsed };
+        }
+        throw new WorkflowError(`AirtableAdapter: unsupported update operation "${operation}"`, {
+            code: 'ADAPTER_OP_UNSUPPORTED',
+            category: 'ENGINE',
+            agentAction: 'report_to_user',
+            retryable: false,
+        });
+    }
+}
+//# sourceMappingURL=airtable-adapter.js.map