@onkeiki/agents 0.1.0

package/dist/services/Observability.js

@@ -0,0 +1,238 @@
+/**
+ * Observability Service
+ *
+ * Allows developers to export turn traces to external providers:
+ * - Braintrust (AI-specific tracing, evals, scoring)
+ * - Axiom (structured log ingestion)
+ * - Generic OTEL (any OpenTelemetry-compatible backend)
+ * - Custom (developer-provided exporter function)
+ *
+ * The platform always records traces internally (14-day retention).
+ * This service ADDITIONALLY exports to the developer's chosen provider.
+ */
+import { Effect, Context } from 'effect';
+export class ObservabilityError {
+    provider;
+    message;
+    cause;
+    _tag = 'ObservabilityError';
+    constructor(provider, message, cause) {
+        this.provider = provider;
+        this.message = message;
+        this.cause = cause;
+    }
+}
+// --- Service Tag ---
+export class Observability extends Context.Tag('Observability')() {
+}
+// --- Provider Factories ---
+/**
+ * Braintrust exporter.
+ * Sends traces as Braintrust spans for AI observability, evals, and scoring.
+ */
+export function braintrustExporter(config) {
+    const baseUrl = config.baseUrl ?? 'https://api.braintrust.dev';
+    return {
+        name: 'braintrust',
+        exportTrace: (trace) => Effect.tryPromise({
+            try: async () => {
+                const spans = trace.spans.map((span) => ({
+                    id: span.spanId,
+                    span_id: span.spanId,
+                    root_span_id: trace.traceId,
+                    parent_id: span.parentSpanId,
+                    name: span.name,
+                    kind: mapSpanKindToBraintrust(span.kind),
+                    start_time: span.startedAt.toISOString(),
+                    end_time: span.endedAt?.toISOString(),
+                    status_code: span.status === 'error' ? 'ERROR' : 'OK',
+                    input: span.input,
+                    output: span.output,
+                    error: span.error,
+                    metadata: {
+                        ...span.metadata,
+                        kind: span.kind,
+                        phone: trace.phone,
+                    },
+                    metrics: span.kind === 'llm' ? {
+                        tokens: (trace.tokensIn + trace.tokensOut) || undefined,
+                        prompt_tokens: trace.tokensIn || undefined,
+                        completion_tokens: trace.tokensOut || undefined,
+                    } : undefined,
+                }));
+                const res = await fetch(`${baseUrl}/v1/project_logs/${encodeURIComponent(config.projectName)}/insert`, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${config.apiKey}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({ events: spans }),
+                });
+                if (!res.ok) {
+                    throw new Error(`Braintrust export failed: ${res.status} ${await res.text()}`);
+                }
+            },
+            catch: (err) => new ObservabilityError('braintrust', String(err), err),
+        }),
+    };
+}
+/**
+ * Axiom exporter.
+ * Sends traces as structured events to an Axiom dataset.
+ */
+export function axiomExporter(config) {
+    const baseUrl = config.baseUrl ?? 'https://api.axiom.co';
+    return {
+        name: 'axiom',
+        exportTrace: (trace) => Effect.tryPromise({
+            try: async () => {
+                // Flatten trace + spans into Axiom events
+                const events = [
+                    // Root trace event
+                    {
+                        _time: trace.startedAt.toISOString(),
+                        type: 'trace',
+                        traceId: trace.traceId,
+                        apiKey: trace.apiKey,
+                        phone: trace.phone,
+                        model: trace.model,
+                        status: trace.status,
+                        durationMs: trace.durationMs,
+                        tokensIn: trace.tokensIn,
+                        tokensOut: trace.tokensOut,
+                        totalSteps: trace.totalSteps,
+                        error: trace.error,
+                        ...trace.metadata,
+                    },
+                    // Individual span events
+                    ...trace.spans.map((span) => ({
+                        _time: span.startedAt.toISOString(),
+                        type: 'span',
+                        traceId: span.traceId,
+                        spanId: span.spanId,
+                        parentSpanId: span.parentSpanId,
+                        name: span.name,
+                        kind: span.kind,
+                        status: span.status,
+                        durationMs: span.durationMs,
+                        error: span.error,
+                        ...span.metadata,
+                    })),
+                ];
+                const res = await fetch(`${baseUrl}/v1/datasets/${config.dataset}/ingest`, {
+                    method: 'POST',
+                    headers: {
+                        'Authorization': `Bearer ${config.apiToken}`,
+                        'Content-Type': 'application/json',
+                        ...(config.orgId ? { 'X-Axiom-Org-Id': config.orgId } : {}),
+                    },
+                    body: JSON.stringify(events),
+                });
+                if (!res.ok) {
+                    throw new Error(`Axiom export failed: ${res.status} ${await res.text()}`);
+                }
+            },
+            catch: (err) => new ObservabilityError('axiom', String(err), err),
+        }),
+    };
+}
+/**
+ * OpenTelemetry (OTLP) exporter.
+ * Sends traces via OTLP/HTTP (JSON) to any OTEL-compatible backend
+ * (Grafana Tempo, Jaeger, Honeycomb, Datadog, etc.)
+ */
+export function otelExporter(config) {
+    const serviceName = config.serviceName ?? 'orchid-sms-agent';
+    return {
+        name: 'otel',
+        exportTrace: (trace) => Effect.tryPromise({
+            try: async () => {
+                const resourceSpans = [{
+                        resource: {
+                            attributes: [
+                                { key: 'service.name', value: { stringValue: serviceName } },
+                                { key: 'orchid.api_key', value: { stringValue: trace.apiKey } },
+                            ],
+                        },
+                        scopeSpans: [{
+                                scope: { name: 'orchid-agents', version: '0.1.0' },
+                                spans: trace.spans.map((span) => ({
+                                    traceId: hexToBase64(trace.traceId),
+                                    spanId: hexToBase64(span.spanId.replace(/-/g, '').slice(0, 16)),
+                                    parentSpanId: span.parentSpanId ? hexToBase64(span.parentSpanId.replace(/-/g, '').slice(0, 16)) : undefined,
+                                    name: span.name,
+                                    kind: mapSpanKindToOtel(span.kind),
+                                    startTimeUnixNano: String(span.startedAt.getTime() * 1_000_000),
+                                    endTimeUnixNano: span.endedAt ? String(span.endedAt.getTime() * 1_000_000) : undefined,
+                                    status: {
+                                        code: span.status === 'error' ? 2 : 1,
+                                        message: span.error,
+                                    },
+                                    attributes: [
+                                        { key: 'orchid.span.kind', value: { stringValue: span.kind } },
+                                        { key: 'orchid.phone', value: { stringValue: trace.phone } },
+                                        ...(span.kind === 'llm' ? [
+                                            { key: 'gen_ai.system', value: { stringValue: 'orchid' } },
+                                            { key: 'gen_ai.request.model', value: { stringValue: trace.model ?? '' } },
+                                            { key: 'gen_ai.usage.prompt_tokens', value: { intValue: String(trace.tokensIn) } },
+                                            { key: 'gen_ai.usage.completion_tokens', value: { intValue: String(trace.tokensOut) } },
+                                        ] : []),
+                                    ],
+                                })),
+                            }],
+                    }];
+                const res = await fetch(`${config.endpoint}/v1/traces`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...config.headers,
+                    },
+                    body: JSON.stringify({ resourceSpans }),
+                });
+                if (!res.ok) {
+                    throw new Error(`OTEL export failed: ${res.status} ${await res.text()}`);
+                }
+            },
+            catch: (err) => new ObservabilityError('otel', String(err), err),
+        }),
+    };
+}
+/**
+ * Custom exporter — developer provides their own export function.
+ */
+export function customExporter(config) {
+    return {
+        name: config.name,
+        exportTrace: (trace) => Effect.tryPromise({
+            try: () => config.exportFn(trace),
+            catch: (err) => new ObservabilityError(config.name, String(err), err),
+        }),
+    };
+}
+// --- Helpers ---
+function mapSpanKindToBraintrust(kind) {
+    switch (kind) {
+        case 'llm': return 'llm';
+        case 'tool': return 'tool';
+        case 'retrieval': return 'retrieval';
+        case 'generation': return 'generation';
+        default: return 'task';
+    }
+}
+function mapSpanKindToOtel(kind) {
+    switch (kind) {
+        case 'llm': return 3; // CLIENT
+        case 'tool': return 3; // CLIENT
+        case 'retrieval': return 3; // CLIENT
+        case 'internal': return 1; // INTERNAL
+        default: return 0; // UNSPECIFIED
+    }
+}
+function hexToBase64(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+    }
+    return btoa(String.fromCharCode(...bytes));
+}
+//# sourceMappingURL=Observability.js.map

package/dist/services/Observability.js.map

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

package/dist/services/Platform.d.ts

@@ -0,0 +1,112 @@
+import { Context, Effect } from 'effect';
+export declare class PlatformError {
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly _tag = "PlatformError";
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Platform client — communicates with the Orchid platform API
+ * to access managed services (memory, browser, sandbox, etc.)
+ */
+export type MemoryFact = {
+    readonly id: string;
+    readonly content: string;
+    readonly category: string;
+    readonly createdAt: Date;
+};
+export type BrowseResult = {
+    readonly sessionId: string;
+    readonly url: string;
+    readonly screenshot?: string;
+    readonly content?: string;
+};
+export type SandboxExecResult = {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+    readonly files?: ReadonlyArray<{
+        path: string;
+        url: string;
+    }>;
+};
+export type HandoffResult = {
+    readonly handoffUrl: string;
+    readonly sessionId: string;
+    readonly status: 'waiting' | 'completed' | 'expired';
+};
+export type EscalationResult = {
+    readonly escalationId: string;
+    readonly routedTo: string;
+    readonly status: 'pending' | 'acknowledged' | 'resolved';
+};
+export type BackgroundJobResult = {
+    readonly jobId: string;
+    readonly status: 'queued' | 'running' | 'completed' | 'failed';
+    readonly result?: unknown;
+};
+export interface PlatformService {
+    readonly memoryRecall: (phone: string, query: string, opts?: {
+        categories?: ReadonlyArray<string>;
+        limit?: number;
+    }) => Effect.Effect<ReadonlyArray<MemoryFact>, PlatformError>;
+    readonly memoryLearn: (phone: string, facts: ReadonlyArray<{
+        content: string;
+        category: string;
+    }>) => Effect.Effect<void, PlatformError>;
+    readonly browse: (instruction: string, opts?: {
+        sessionId?: string;
+        screenshot?: boolean;
+    }) => Effect.Effect<BrowseResult, PlatformError>;
+    readonly handoff: (opts: {
+        phone: string;
+        instruction: string;
+        url?: string;
+        timeoutMinutes?: number;
+    }) => Effect.Effect<HandoffResult, PlatformError>;
+    readonly exec: (command: string, opts?: {
+        phone?: string;
+        persistent?: boolean;
+        timeout?: number;
+    }) => Effect.Effect<SandboxExecResult, PlatformError>;
+    readonly writeFile: (path: string, content: string, opts?: {
+        phone?: string;
+    }) => Effect.Effect<void, PlatformError>;
+    readonly readFile: (path: string, opts?: {
+        phone?: string;
+    }) => Effect.Effect<string, PlatformError>;
+    readonly runJob: (opts: {
+        name: string;
+        command: string;
+        phone?: string;
+        timeout?: number;
+    }) => Effect.Effect<BackgroundJobResult, PlatformError>;
+    readonly getJobStatus: (jobId: string) => Effect.Effect<BackgroundJobResult, PlatformError>;
+    readonly escalate: (opts: {
+        phone: string;
+        reason: string;
+        context?: string;
+        routes?: {
+            webhook?: string;
+            slack?: {
+                channel: string;
+            };
+            email?: string;
+        };
+    }) => Effect.Effect<EscalationResult, PlatformError>;
+    readonly extractFacts: (phone: string, messages: ReadonlyArray<{
+        content: string;
+        direction: 'inbound' | 'outbound';
+    }>) => Effect.Effect<ReadonlyArray<{
+        content: string;
+        category: string;
+    }>, PlatformError>;
+    readonly transcribeAudio: (url: string) => Effect.Effect<string, PlatformError>;
+    readonly describeImage: (url: string, prompt?: string) => Effect.Effect<string, PlatformError>;
+    readonly extractDocument: (url: string) => Effect.Effect<string, PlatformError>;
+}
+declare const Platform_base: Context.TagClass<Platform, "@onkeiki/agents/Platform", PlatformService>;
+export declare class Platform extends Platform_base {
+}
+export {};
+//# sourceMappingURL=Platform.d.ts.map

package/dist/services/Platform.d.ts.map

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

package/dist/services/Platform.js

@@ -0,0 +1,13 @@
+import { Context, Effect } from 'effect';
+export class PlatformError {
+    message;
+    cause;
+    _tag = 'PlatformError';
+    constructor(message, cause) {
+        this.message = message;
+        this.cause = cause;
+    }
+}
+export class Platform extends Context.Tag('@onkeiki/agents/Platform')() {
+}
+//# sourceMappingURL=Platform.js.map

package/dist/services/Platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Platform.js","sourceRoot":"","sources":["../../src/services/Platform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAExC,MAAM,OAAO,aAAa;IAEH,OAAO;IAAmB,KAAK;IAD3C,IAAI,GAAG,eAAe,CAAA;IAC/B,YAAqB,OAAe,EAAW,KAAe;uBAAzC,OAAO;qBAAmB,KAAK;IAAa,CAAC;CACnE;AAoHD,MAAM,OAAO,QAAS,SAAQ,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,EAGlE;CAAG"}

package/dist/services/PluginDb.d.ts

@@ -0,0 +1,44 @@
+import { Context, Effect } from 'effect';
+import { StorageError } from './Storage.js';
+/**
+ * Generic query interface for plugins that need their own persistence.
+ *
+ * Provided by the active storage adapter (Postgres, MongoDB, etc.) so
+ * plugins can create and query their own tables/collections without
+ * extending the core `StorageService` interface.
+ *
+ * The storage adapter is responsible for:
+ * - Running plugin migrations at boot (see `PluginMigration`)
+ * - Providing a `PluginDb` backed by the same connection pool / client
+ *
+ * Plugins access this via `PluginDb` in their tools and hooks.
+ */
+export interface PluginDbService {
+    /** Run a query that returns rows. */
+    readonly query: <T = Record<string, unknown>>(sql: string, params?: readonly unknown[]) => Effect.Effect<T[], StorageError>;
+    /** Run a query that returns a single row or null. */
+    readonly queryOne: <T = Record<string, unknown>>(sql: string, params?: readonly unknown[]) => Effect.Effect<T | null, StorageError>;
+    /** Run a statement that doesn't return rows (INSERT, UPDATE, DELETE). */
+    readonly execute: (sql: string, params?: readonly unknown[]) => Effect.Effect<void, StorageError>;
+}
+declare const PluginDb_base: Context.TagClass<PluginDb, "@onkeiki/agents/PluginDb", PluginDbService>;
+export declare class PluginDb extends PluginDb_base {
+}
+/**
+ * A single migration contributed by a plugin. Migrations are tracked in
+ * a `smskit_plugin_migrations` table and only run once per (pluginId, version).
+ *
+ * Migrations are NEVER rolled back when a plugin is disabled — disabling
+ * a plugin simply stops running its code, but the tables and data remain
+ * intact. This prevents accidental data loss.
+ */
+export type PluginMigration = {
+    /** Monotonically increasing version number (1, 2, 3, ...). */
+    readonly version: number;
+    /** Human-readable name for logging. */
+    readonly name: string;
+    /** SQL statement(s) to execute. May contain multiple statements separated by semicolons. */
+    readonly up: string;
+};
+export {};
+//# sourceMappingURL=PluginDb.d.ts.map

package/dist/services/PluginDb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginDb.d.ts","sourceRoot":"","sources":["../../src/services/PluginDb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,YAAY,CAAC,CAAA;IAE3H,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,EAAE,YAAY,CAAC,CAAA;IAEnI,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;CAClG;;AAED,qBAAa,QAAS,SAAQ,aAG3B;CAAG;AAEN;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACpB,CAAA"}

package/dist/services/PluginDb.js

@@ -0,0 +1,5 @@
+import { Context, Effect } from 'effect';
+import { StorageError } from './Storage.js';
+export class PluginDb extends Context.Tag('@onkeiki/agents/PluginDb')() {
+}
+//# sourceMappingURL=PluginDb.js.map

package/dist/services/PluginDb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PluginDb.js","sourceRoot":"","sources":["../../src/services/PluginDb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AA0B3C,MAAM,OAAO,QAAS,SAAQ,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,EAGlE;CAAG"}

package/dist/services/Sandbox.d.ts

@@ -0,0 +1,68 @@
+import { Context } from 'effect';
+/**
+ * Result of executing a command in a sandbox.
+ */
+export type SandboxExecResult = {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+};
+/**
+ * A handle to a running sandbox instance. Provides shell execution and
+ * network access needed by plugins that run daemons inside sandboxes
+ * (e.g. Executor.sh for custom MCP servers).
+ */
+export interface SandboxHandle {
+    /** Execute a shell command inside the sandbox. */
+    readonly exec: (command: string, opts?: {
+        readonly timeoutSeconds?: number;
+        readonly cwd?: string;
+    }) => Promise<SandboxExecResult>;
+    /** Get a publicly-reachable URL for a port exposed inside the sandbox. */
+    readonly getPublicUrl: (port: number, expiresInSeconds?: number) => Promise<string>;
+    /** Absolute home directory of the sandbox user. */
+    readonly getHomeDir: () => Promise<string>;
+    /**
+     * Absolute path of a durable data directory backed by persistent storage
+     * (e.g. a Daytona volume) that survives sandbox stop/delete, or `null` when
+     * no durable storage is attached. Daemons that keep state (SQLite, OAuth
+     * credentials) use it as a backup/restore target across sandbox recreation.
+     */
+    readonly getPersistentExecutorDataDir?: () => Promise<string | null>;
+}
+/**
+ * Abstract sandbox provider — any sandbox company (Daytona, E2B, Runloop,
+ * Modal, etc.) can implement this interface and plug into AgentKit.
+ *
+ * The provider is responsible for lifecycle management (create, start, stop,
+ * reuse) of sandboxes. Each `scope` string identifies an isolation boundary
+ * (e.g. `"apiKey:phone"` for per-user sandboxes).
+ *
+ * @example
+ * ```ts
+ * // Community adapter: @onkeiki/agents-sandbox-daytona
+ * import { Daytona } from '@daytona/sdk'
+ *
+ * export function daytona(opts: { apiKey: string; snapshot?: string }): SandboxProvider {
+ *   return {
+ *     resolve: async (scope) => {
+ *       const sandbox = await getOrCreate(scope)
+ *       return {
+ *         exec: (cmd, o) => sandbox.process.executeCommand(cmd, o?.cwd, {}, o?.timeoutSeconds),
+ *         getPublicUrl: (port, exp) => sandbox.getSignedPreviewUrl(port, exp).then(r => r.url),
+ *         getHomeDir: () => sandbox.getUserHomeDir().then(h => h ?? '/root'),
+ *       }
+ *     },
+ *   }
+ * }
+ * ```
+ */
+export interface SandboxProviderService {
+    /** Get or create a sandbox for the given scope. */
+    readonly resolve: (scope: string) => Promise<SandboxHandle>;
+}
+declare const SandboxProvider_base: Context.TagClass<SandboxProvider, "@onkeiki/agents/SandboxProvider", SandboxProviderService>;
+export declare class SandboxProvider extends SandboxProvider_base {
+}
+export {};
+//# sourceMappingURL=Sandbox.d.ts.map

package/dist/services/Sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sandbox.d.ts","sourceRoot":"","sources":["../../src/services/Sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAEhC;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,CACb,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,KAC/D,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAE/B,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAEnF,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IAE1C;;;;;OAKG;IACH,QAAQ,CAAC,4BAA4B,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;CACrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,sBAAsB;IACrC,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAA;CAC5D;;AAED,qBAAa,eAAgB,SAAQ,oBAGlC;CAAG"}

package/dist/services/Sandbox.js

@@ -0,0 +1,4 @@
+import { Context } from 'effect';
+export class SandboxProvider extends Context.Tag('@onkeiki/agents/SandboxProvider')() {
+}
+//# sourceMappingURL=Sandbox.js.map

package/dist/services/Sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sandbox.js","sourceRoot":"","sources":["../../src/services/Sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAA;AAsEhC,MAAM,OAAO,eAAgB,SAAQ,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,EAGhF;CAAG"}

package/dist/services/Steering.d.ts

@@ -0,0 +1,46 @@
+import { Context, Effect, Queue } from 'effect';
+import type { InboundMessage } from '../types/index.js';
+export type SteeringDecision = {
+    readonly type: 'batch';
+    readonly messages: ReadonlyArray<InboundMessage>;
+} | {
+    readonly type: 'interrupt';
+    readonly messages: ReadonlyArray<InboundMessage>;
+} | {
+    readonly type: 'append';
+    readonly message: InboundMessage;
+} | {
+    readonly type: 'queue';
+    readonly message: InboundMessage;
+};
+export type TurnState = {
+    readonly phone: string;
+    readonly status: 'idle' | 'debouncing' | 'processing';
+    readonly pending: ReadonlyArray<InboundMessage>;
+    readonly currentTurnStartedAt?: Date;
+};
+export interface SteeringService {
+    /**
+     * Enqueue an inbound message. Steering decides when to
+     * release it as a turn (after debounce window) or interrupt
+     * an in-progress turn.
+     */
+    readonly enqueue: (msg: InboundMessage) => Effect.Effect<void>;
+    /**
+     * Subscribe to turn decisions. The agent runtime consumes these.
+     */
+    readonly decisions: Effect.Effect<Queue.Dequeue<SteeringDecision>>;
+    /**
+     * Signal that the current turn for a phone has completed.
+     */
+    readonly turnCompleted: (phone: string) => Effect.Effect<void>;
+    /**
+     * Get current state for a phone number.
+     */
+    readonly getState: (phone: string) => Effect.Effect<TurnState>;
+}
+declare const Steering_base: Context.TagClass<Steering, "@onkeiki/agents/Steering", SteeringService>;
+export declare class Steering extends Steering_base {
+}
+export {};
+//# sourceMappingURL=Steering.d.ts.map

package/dist/services/Steering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Steering.d.ts","sourceRoot":"","sources":["../../src/services/Steering.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAc,MAAM,QAAQ,CAAA;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGvD,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;CAAE,GAChF;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAA;AAEhE,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,YAAY,CAAA;IACrD,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;IAC/C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,IAAI,CAAA;CACrC,CAAA;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAE9D;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAA;IAElE;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAE9D;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;CAC/D;;AAED,qBAAa,QAAS,SAAQ,aAG3B;CAAG"}

package/dist/services/Steering.js

@@ -0,0 +1,4 @@
+import { Context, Effect, Queue, Fiber, Ref } from 'effect';
+export class Steering extends Context.Tag('@onkeiki/agents/Steering')() {
+}
+//# sourceMappingURL=Steering.js.map

package/dist/services/Steering.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Steering.js","sourceRoot":"","sources":["../../src/services/Steering.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAA;AAyC3D,MAAM,OAAO,QAAS,SAAQ,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,EAGlE;CAAG"}