@cybernetyx1/atlasflow-runtime 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,739 @@
+import { c as AnyTool, d as AgentRuntimeConfig, C as CreatedAgent, W as WorkflowDef, E as EngineTool, R as Rule, e as AgentHooks, T as ToolDefinition, f as RawTool, S as Skill, g as ToolChoice, A as AgentEngine, h as CompactionConfig, i as EngineRunInput, j as EngineHooks, k as EngineRunResult } from './channel-Dv3Hv1ee.js';
+export { l as AgentCreateContext, m as AgentDefinition, a as AgentProfile, n as ChannelAccepted, o as ChannelContext, b as ChannelDefinition, p as ChannelDispatch, q as ChannelMode, r as ChannelResult, s as ContextPack, t as ContextPackItem, u as DurabilityConfig, v as DurableExecutionMeta, D as DurableExecutionRunner, H as HookDecision, w as InvokeOptions, I as InvokeResult, P as ProviderModelSettings, x as ProviderSettings, y as RuleEnforcePoint, z as SlackRequestSignatureOptions, B as ToolApprovalPolicy, F as WorkflowContext, G as WorkflowDefSchema, J as WorkflowRunResult, K as WorkflowState, L as WorkflowStep, M as advanceWorkflow, N as applyProfile, O as approveGate, Q as createAgent, U as defaultEngine, V as defineAgent, X as defineAgentProfile, Y as defineChannel, Z as defineTool, _ as dispatchWorkflow, $ as genId, a0 as getDefaultPersistence, a1 as invokeAgent, a2 as isChannelDefinition, a3 as isCreatedAgent, a4 as isRawTool, a5 as parseWorkflowDef, a6 as rawTool, a7 as recoverRuns, a8 as recoverWorkflows, a9 as resolveAnyTool, aa as resolveTool, ab as startWorkflow, ac as verifyGithubWebhookSignature, ad as verifySlackRequestSignature, ae as waitingGate } from './channel-Dv3Hv1ee.js';
+import * as v from 'valibot';
+import { GenericSchema, InferOutput } from 'valibot';
+import { b as SandboxFactory, c as SessionEnv, e as ShellResult, S as SandboxNetworkPolicy, C as Command, A as AtlasFs } from './command-kxrqWIH7.js';
+export { B as BaseSandboxEnv, a as CommandExecutor, f as CommandExecutorResult, E as ExecOptions, F as FileStat, R as ResolvedSandboxAllowedUrl, g as ResolvedSandboxNetworkPolicy, h as SandboxAllowedUrl, i as SandboxAllowedUrlEntry, j as SandboxCascadeEntry, k as SandboxCascadeProvider, l as SandboxEnvHeaderRef, m as SandboxHeaderValue, n as SandboxHttpMethod, o as SandboxLifecycleDefinition, p as SandboxSessionContext, q as createCwdSessionEnv, r as createScopedSessionEnv, d as defineCommand, s as defineSandbox, t as isSandboxFactory, u as makeFs, v as mergeCommands, w as normalizeCommandExecutor, x as resolveSandboxNetworkPolicy, y as sandboxCascade, z as sandboxHeaderFromEnv, D as writeFileCreatingParents } from './command-kxrqWIH7.js';
+import { E as EventBus, M as ModelConfig, T as ThinkingLevel, o as PromptImage, p as SessionStore, U as Usage, n as Message } from './index-UFTgKRK4.js';
+export { q as AssistantMessage, A as AtlasEvent, C as CacheRetention, d as DurableStreamMessage, r as DurableStreamProducerState, e as DurableStreamProducerTuple, D as DurableStreamRecord, l as DurableStreamSubscriptionAckInput, k as DurableStreamSubscriptionClaim, h as DurableStreamSubscriptionCreateInput, s as DurableStreamSubscriptionError, t as DurableStreamSubscriptionErrorCode, u as DurableStreamSubscriptionLink, v as DurableStreamSubscriptionLinkType, j as DurableStreamSubscriptionRecord, i as DurableStreamSubscriptionResult, w as DurableStreamSubscriptionStatus, x as DurableStreamSubscriptionStoreBase, m as DurableStreamSubscriptionStreamInfo, y as DurableStreamSubscriptionType, z as EventSubscriber, I as InMemoryRunStore, B as InMemorySessionStore, F as InMemoryStreamStore, G as InMemorySubscriptionStore, K as KvLike, O as OperationKind, P as PersistenceAdapter, H as PersistenceAdapterOptions, R as RunRecord, a as RunStatus, J as RunStore, S as SessionData, L as StopReason, c as StreamAppendOptions, b as StreamCreateOptions, f as StreamProducerAppendResult, g as StreamProducerCloseResult, N as StreamProducerResult, Q as StreamStore, V as SubscriptionStore, W as ToolResultMessage, X as UserMessage, Y as WebhookDeliveryOptions, Z as WebhookHostResolver, _ as addUsage, $ as emptyUsage, a0 as inMemoryAdapter, a1 as isJsonStreamContentType, a2 as kvAdapter, a3 as normalizeStreamContentType, a4 as observe, a5 as streamMessageBytes } from './index-UFTgKRK4.js';
+import { IFileSystem, BashOptions } from 'just-bash';
+export { ProviderRegistration, ProviderRegistrationError, getRegisteredApiKey, getRegisteredStoreResponses, hasRegisteredProvider, registerProvider, resetProvidersForTests, resolveRegisteredModel } from './providers.js';
+export { ApiProvider, getApiProvider, getApiProviders, registerApiProvider, unregisterApiProviders } from '@earendil-works/pi-ai';
+
+/**
+ * Persona manifest — the frozen v1 schema (Atlas Brain compile target).
+ *
+ * A persona is DATA, not code: identity + loadout + connector slots, authored
+ * by the Brain UI (or by hand as JSON) and hydrated into a runnable agent by
+ * `personaAgent()`. This is the keystone of the Brain↔AtlasFlow interop:
+ * deploying a UI-built persona never requires writing TypeScript.
+ *
+ *   Brain kind        → manifest field
+ *   ────────────────────────────────────────────
+ *   Persona identity  → identity.{role,disposition,voice,taste,instructions}
+ *   Skills            → loadout.skills (SKILL.md-compatible shape)
+ *   Context packs     → loadout.contextPacks (mount: context | sandbox)
+ *   Standards         → loadout.standards (advisory → system context)
+ *   Rules             → loadout.rules (binding → enforcement hooks)
+ *   Workflows         → loadout.workflows (gated, role-slotted; see workflow.ts)
+ *   Sub-personas      → loadout.personas (task-tool delegation targets)
+ *   Triggers          → loadout.triggers (webhook / cron intents)
+ *   Connector slots   → slots (credentials bound by the workspace, never carried)
+ *   Provenance        → provenance / per-artifact provenance (metadata only —
+ *                       AtlasFlow surfaces it, the Brain judges it)
+ */
+
+declare const SlotSchema: v.ObjectSchema<{
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly type: v.PicklistSchema<["credential", "mcp", "tool", "sandbox", "memory"], undefined>;
+    /** For credential slots: the env var the workspace must bind. */
+    readonly env: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly required: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+declare const PersonaManifestSchema: v.ObjectSchema<{
+    /** Optional editor schema reference. Ignored by the runtime. */
+    readonly $schema: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    /** Manifest version. v1 is frozen; breaking changes bump it. */
+    readonly atlasflow: v.LiteralSchema<1, undefined>;
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly identity: v.OptionalSchema<v.ObjectSchema<{
+        readonly role: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly disposition: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly voice: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly taste: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly instructions: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly model: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly loadout: v.OptionalSchema<v.ObjectSchema<{
+        readonly skills: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+            readonly description: v.OptionalSchema<v.StringSchema<undefined>, "">;
+            /** Alias accepted on import for agentskills.io round-tripping. */
+            readonly when_to_use: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly body: v.StringSchema<undefined>;
+            readonly allowedTools: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+            readonly provenance: v.OptionalSchema<v.PicklistSchema<["earned", "taught", "ingested", "researched", "inherited"], undefined>, "taught">;
+        }, undefined>, undefined>, undefined>;
+        readonly contextPacks: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+            readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly version: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly mount: v.OptionalSchema<v.PicklistSchema<["context", "sandbox"], undefined>, undefined>;
+            readonly items: v.ArraySchema<v.ObjectSchema<{
+                readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                readonly content: v.StringSchema<undefined>;
+            }, undefined>, undefined>;
+            readonly provenance: v.OptionalSchema<v.PicklistSchema<["earned", "taught", "ingested", "researched", "inherited"], undefined>, "taught">;
+        }, undefined>, undefined>, undefined>;
+        readonly standards: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+            readonly content: v.StringSchema<undefined>;
+            readonly provenance: v.OptionalSchema<v.PicklistSchema<["earned", "taught", "ingested", "researched", "inherited"], undefined>, "taught">;
+        }, undefined>, undefined>, undefined>;
+        readonly rules: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+            readonly enforce: v.PicklistSchema<["before_prompt", "before_tool", "after_tool"], undefined>;
+            readonly tools: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+            readonly pattern: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly action: v.OptionalSchema<v.PicklistSchema<["block", "warn"], undefined>, "block">;
+            readonly message: v.StringSchema<undefined>;
+            readonly provenance: v.OptionalSchema<v.PicklistSchema<["earned", "taught", "ingested", "researched", "inherited"], undefined>, "taught">;
+        }, undefined>, undefined>, undefined>;
+        readonly workflows: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+            readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly steps: v.SchemaWithPipe<readonly [v.ArraySchema<v.VariantSchema<"kind", [v.ObjectSchema<{
+                readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                readonly kind: v.LiteralSchema<"prompt", undefined>;
+                readonly prompt: v.StringSchema<undefined>;
+                readonly persona: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly model: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                readonly kind: v.LiteralSchema<"skill", undefined>;
+                readonly skill: v.StringSchema<undefined>;
+                readonly input: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+                readonly persona: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, v.ObjectSchema<{
+                readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+                readonly kind: v.LiteralSchema<"gate", undefined>;
+                readonly title: v.StringSchema<undefined>;
+                readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>], undefined>, undefined>, v.MinLengthAction<({
+                id: string;
+                kind: "prompt";
+                prompt: string;
+                persona?: string | undefined;
+                model?: string | undefined;
+            } | {
+                id: string;
+                kind: "skill";
+                skill: string;
+                input?: string | undefined;
+                persona?: string | undefined;
+            } | {
+                id: string;
+                kind: "gate";
+                title: string;
+                description?: string | undefined;
+            })[], 1, undefined>]>;
+            readonly roleSlots: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+        }, undefined>, undefined>, undefined>;
+        readonly personas: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+            readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+            readonly model: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+            readonly instructions: v.StringSchema<undefined>;
+            readonly provenance: v.OptionalSchema<v.PicklistSchema<["earned", "taught", "ingested", "researched", "inherited"], undefined>, "taught">;
+        }, undefined>, undefined>, undefined>;
+        readonly triggers: v.OptionalSchema<v.ObjectSchema<{
+            readonly webhook: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly cron: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly slots: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly type: v.PicklistSchema<["credential", "mcp", "tool", "sandbox", "memory"], undefined>;
+        /** For credential slots: the env var the workspace must bind. */
+        readonly env: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly required: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+        readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>, undefined>;
+    readonly defaults: v.OptionalSchema<v.ObjectSchema<{
+        readonly thinkingLevel: v.OptionalSchema<v.PicklistSchema<["off", "minimal", "low", "medium", "high", "xhigh"], undefined>, undefined>;
+        readonly headless: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly builtinTools: v.OptionalSchema<v.UnionSchema<[v.BooleanSchema<undefined>, v.ArraySchema<v.StringSchema<undefined>, undefined>], undefined>, undefined>;
+        readonly compaction: v.OptionalSchema<v.UnionSchema<[v.LiteralSchema<false, undefined>, v.ObjectSchema<{
+            readonly threshold: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+            readonly thresholdTokens: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+            readonly keepRecent: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        }, undefined>], undefined>, undefined>;
+        readonly durability: v.OptionalSchema<v.ObjectSchema<{
+            readonly retry: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+            readonly timeoutMs: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** Opaque Brain metadata (lineage, fork base, provenance summary). */
+    readonly provenance: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
+}, undefined>;
+type PersonaManifest = v.InferOutput<typeof PersonaManifestSchema>;
+type PersonaSlot = v.InferOutput<typeof SlotSchema>;
+declare function parsePersonaManifest(value: unknown): PersonaManifest;
+interface PersonaBindings {
+    /** Sandbox for the persona's sandbox slot (workspace-bound, never carried). */
+    sandbox?: SandboxFactory | ((ctx: {
+        id: string;
+        env: Record<string, unknown>;
+    }) => SandboxFactory);
+    /**
+     * Extra tools bound by the workspace (e.g. MCP connections for mcp slots).
+     * Can be static, or a per-invocation factory so Workers can open MCP
+     * connections inside request scope and close them after the run settles.
+     * Kept for compatibility; prefer toolSlots for named connector slots.
+     */
+    tools?: PersonaToolsBinding;
+    /**
+     * Slot-scoped tool bindings keyed by manifest slot name. Use this for
+     * non-MCP integrations such as GitHub or Slack, and for multiple tool slots
+     * that must fail independently when one binding is missing.
+     */
+    toolSlots?: Record<string, PersonaToolsBinding>;
+    /** Override how manifest skills are exposed. Defaults to historical callable skill tools. */
+    skillLoading?: AgentRuntimeConfig["skillLoading"];
+    /** Override how manifest context packs are exposed. Defaults to historical eager context. */
+    contextLoading?: AgentRuntimeConfig["contextLoading"];
+}
+interface PersonaBindingContext {
+    id: string;
+    env: Record<string, unknown>;
+    manifest: PersonaManifest;
+    slot?: PersonaSlot;
+}
+interface PersonaToolBindingResult {
+    tools: AnyTool[];
+    /** Preferred cleanup hook for per-invocation resources. */
+    cleanup?: () => void | Promise<void>;
+    /** Alias for MCP-style connections. */
+    close?: () => Promise<void>;
+}
+type PersonaToolsBinding = AnyTool | AnyTool[] | PersonaToolBindingResult | ((ctx: PersonaBindingContext) => AnyTool | AnyTool[] | PersonaToolBindingResult | Promise<AnyTool | AnyTool[] | PersonaToolBindingResult>);
+interface ResolvedPersonaToolBindings {
+    tools: AnyTool[];
+    toolsBySlot: Record<string, AnyTool[]>;
+}
+/** Validate that the workspace bound every required slot; throw listing gaps. */
+declare function validateSlots(m: PersonaManifest, env: Record<string, unknown>, bindings?: PersonaBindings, resolvedTools?: ResolvedPersonaToolBindings): void;
+/**
+ * Hydrate a persona manifest into a runnable agent. Slot validation happens
+ * at initialization (fail fast, before any model call).
+ */
+declare function personaAgent(manifest: unknown, bindings?: PersonaBindings): CreatedAgent;
+/** The persona's authored workflows, keyed by name (for createApp/executor). */
+declare function personaWorkflows(manifest: unknown): Record<string, WorkflowDef>;
+/**
+ * The persona's workflows as executor mounts: each carries the skills and
+ * default model the workflow's steps resolve against.
+ */
+declare function personaWorkflowMounts(manifest: unknown): Record<string, {
+    def: WorkflowDef;
+    skills: {
+        name: string;
+        description: string;
+        body: string;
+    }[];
+    defaultModel: string;
+    defaultPersona: string;
+    profiles: {
+        name: string;
+        model?: string;
+        instructions: string;
+    }[];
+}>;
+/** The persona's trigger intents (manifest → deploy wiring). */
+declare function personaTriggers(manifest: unknown): {
+    webhook?: boolean;
+    cron?: string;
+};
+
+/**
+ * Rule enforcement — the Atlas Brain normative·binding primitive at runtime.
+ *
+ * Declarative `Rule`s and programmatic `AgentHooks` compile into one guard
+ * with three enforcement points:
+ *   before_prompt — blocks the run before any model call
+ *   before_tool   — blocks a tool call (the model sees the rule's message as
+ *                   a tool error and can adapt)
+ *   after_tool    — blocks a tool result from reaching the model
+ * `warn` rules emit a rule_triggered event and let the action proceed.
+ */
+
+declare class RuleViolation extends Error {
+    rule: string;
+    code: string;
+    constructor(rule: string, message: string);
+}
+interface RuleGuard {
+    /** Throws RuleViolation when a before_prompt rule blocks. */
+    checkPrompt(text: string): Promise<void>;
+    /** Wrap a tool so before_tool/after_tool rules apply to every call. */
+    wrapTool(tool: EngineTool): EngineTool;
+}
+declare function makeRuleGuard(rules: Rule[], hooks: AgentHooks | undefined, bus: EventBus, runId: string | undefined): RuleGuard;
+
+declare const MemorySearchParametersSchema: v.ObjectSchema<{
+    readonly query: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly limit: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
+    readonly scope: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+type MemorySearchParameters = v.InferOutput<typeof MemorySearchParametersSchema>;
+interface MemorySearchResult {
+    id?: string;
+    title?: string;
+    text: string;
+    score?: number;
+    metadata?: Record<string, unknown>;
+}
+interface MemoryConnectorOptions {
+    name?: string;
+    description?: string;
+    search: (args: MemorySearchParameters, signal?: AbortSignal) => MemorySearchResult[] | Promise<MemorySearchResult[]>;
+}
+/**
+ * Define a read-only memory retrieval tool for a persona `memory` slot.
+ *
+ * Memory stays workspace-bound: the manifest declares the slot, while the
+ * deployment supplies this tool through `bindings.toolSlots.<slotName>`.
+ */
+declare function defineMemoryConnector(options: MemoryConnectorOptions): ToolDefinition<typeof MemorySearchParametersSchema>;
+
+type HttpConnectionMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
+interface HttpConnectionOperation {
+    name: string;
+    description: string;
+    method?: HttpConnectionMethod;
+    path: string;
+    /** JSON Schema for arguments passed to the operation. */
+    parameters?: Record<string, unknown>;
+    /** Args copied into URI template slots such as /repos/{owner}/{repo}. */
+    pathParams?: string[];
+    /** Args serialized as query parameters. Defaults to remaining args for GET/HEAD. */
+    queryParams?: string[];
+    /** Arg used as the request body. Defaults to remaining args for non-GET methods. */
+    bodyParam?: string;
+    /** Static or computed request body for operations with known payloads. */
+    body?: unknown | ((args: Record<string, unknown>, ctx: PersonaBindingContext) => unknown | Promise<unknown>);
+    headers?: Record<string, string> | ((ctx: PersonaBindingContext) => Record<string, string> | Promise<Record<string, string>>);
+}
+interface HttpConnectionOptions {
+    /** Connection/slot name, used as the default tool namespace. */
+    name: string;
+    /** Static endpoint root. Prefer baseUrlEnv for deployed apps. */
+    baseUrl?: string;
+    /** Env var holding the endpoint root. */
+    baseUrlEnv?: string;
+    headers?: Record<string, string> | ((ctx: PersonaBindingContext) => Record<string, string> | Promise<Record<string, string>>);
+    operations: HttpConnectionOperation[];
+    /**
+     * lazy: expose <name>__search and <name>__call only.
+     * direct: expose one tool per operation.
+     * both: expose both surfaces.
+     */
+    expose?: "lazy" | "direct" | "both";
+    fetch?: typeof fetch;
+    allowInsecureHttp?: boolean;
+    allowPrivateNetwork?: boolean;
+}
+declare function defineHttpConnection(options: HttpConnectionOptions): (ctx: PersonaBindingContext) => Promise<PersonaToolBindingResult>;
+
+/**
+ * Built-in agent tools — read, write, edit, bash, grep, glob — implemented
+ * against the vendor-neutral SessionEnv, so they behave identically on the
+ * local sandbox, a remote connector (Docker/E2B/Daytona), or workerd.
+ *
+ * These are what make an AtlasFlow agent a *working* agent out of the box:
+ * any agent with a sandbox gets them automatically (config `builtinTools:
+ * false` opts out). The `task` tool is built in runtime.ts because it needs
+ * the engine; everything here needs only the sandbox.
+ */
+
+interface BuiltinToolOptions {
+    /** Restrict to a subset of tool names (default: all). */
+    include?: string[];
+    /** Truncate tool output beyond this many characters (default 50_000). */
+    maxOutputChars?: number;
+}
+declare function builtinTools(env: SessionEnv, options?: BuiltinToolOptions): EngineTool[];
+declare const BUILTIN_TOOL_NAMES: readonly ["read", "write", "edit", "bash", "grep", "glob", "task"];
+
+/**
+ * MCP (Model Context Protocol) tool integration.
+ *
+ * `connectMcpServer` connects to an MCP server — a local process over stdio,
+ * or a remote server over streamable HTTP (with SSE fallback) — lists its
+ * tools, and returns them as RawTools usable directly in an agent's `tools`
+ * config. The connection's `close()` shuts the transport down.
+ */
+
+interface McpServerOptions {
+    /** Executable to launch a stdio MCP server (e.g. "node", "npx"). */
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    /** URL of a remote MCP server (streamable HTTP, with SSE fallback). */
+    url?: string;
+    /** Force a transport instead of inferring from command/url. */
+    transport?: "stdio" | "http" | "sse";
+    /** Extra headers for remote transports (e.g. authorization). */
+    headers?: Record<string, string>;
+    /** Client name reported to the server. */
+    name?: string;
+    /** Namespace tool names as `mcp__<prefix>__<tool>` to avoid collisions. */
+    prefix?: string;
+    /** Disable namespacing. Defaults to true for MCP safety. */
+    namespace?: boolean;
+    /** Additional request configuration for remote transports. */
+    requestInit?: RequestInit;
+    /** Custom fetch used by remote transports. */
+    fetch?: typeof fetch;
+    /** Per-request MCP timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Reset request timeout when the server sends progress. */
+    resetTimeoutOnProgress?: boolean;
+}
+interface McpConnection {
+    name: string;
+    tools: RawTool[];
+    close(): Promise<void>;
+}
+declare function connectMcpServer(options: McpServerOptions): Promise<McpConnection>;
+
+/**
+ * Runtime workspace context discovery.
+ *
+ * Agents should not have to hard-code every project instruction or local skill in
+ * their agent file. This discovers AGENTS.md/CLAUDE.md and lazy local skills from
+ * the sandbox cwd, providing a runtime context layer while
+ * keeping Atlas's persona/context-pack model intact.
+ */
+
+interface WorkspaceSkill extends Skill {
+    readonly __atlasWorkspaceSkill: true;
+    readonly directory: string;
+    readonly skillMdPath: string;
+}
+interface DiscoveredSessionContext {
+    instructions?: string;
+    workspaceSkills: WorkspaceSkill[];
+}
+declare function isWorkspaceSkill(skill: Skill): skill is WorkspaceSkill;
+declare function discoverSessionContext(env: SessionEnv, definitionSkills?: readonly Skill[]): Promise<DiscoveredSessionContext>;
+declare function loadWorkspaceSkill(env: SessionEnv, skill: WorkspaceSkill): Promise<Skill>;
+interface ParseSkillOptions {
+    directoryName: string;
+    path: string;
+}
+declare function parseSkillMarkdown(content: string, options: ParseSkillOptions): Skill;
+
+/**
+ * Default virtual sandbox backed by just-bash.
+ *
+ * This gives agents a filesystem and shell without a host/container sandbox.
+ * It is intentionally in-memory and per session unless the caller supplies a
+ * Bash factory that shares its filesystem in the factory closure.
+ */
+
+interface BashLike {
+    fs: IFileSystem;
+    exec(command: string, options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        signal?: AbortSignal;
+    }): Promise<ShellResult>;
+    getCwd(): string;
+    registerCommand?(command: {
+        name: string;
+        trusted?: boolean;
+        execute(args: string[], ctx?: {
+            signal?: AbortSignal;
+        }): Promise<ShellResult>;
+    }): void;
+}
+type BashFactory = () => BashLike | Promise<BashLike>;
+interface VirtualSandboxOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    /**
+     * Network policy for shell network commands such as curl/wget. Header
+     * transforms are resolved outside the sandbox, so credentials do not enter
+     * the process environment.
+     */
+    network?: SandboxNetworkPolicy;
+    bash?: Omit<BashOptions, "cwd" | "env" | "fs">;
+}
+declare function bash(factory: BashFactory): SandboxFactory;
+declare function bashFactoryToSessionEnv(factory: BashFactory): Promise<SessionEnv>;
+declare function virtualSandbox(options?: VirtualSandboxOptions): SandboxFactory;
+
+/**
+ * CallHandle — an awaitable that is also cancellable. `await session.prompt(...)`
+ * resolves the result; `.abort()` cancels in-flight model/tool work via the
+ * AbortSignal threaded into the engine.
+ */
+interface CallHandle<T> extends PromiseLike<T> {
+    readonly signal: AbortSignal;
+    abort(reason?: unknown): void;
+}
+declare function makeCall<T>(run: (signal: AbortSignal) => Promise<T>, parentSignal?: AbortSignal): CallHandle<T>;
+
+/**
+ * Session — one conversation thread with the model. Owns its message history
+ * (persisted via SessionStore) and exposes prompt / skill / task plus fs+shell.
+ */
+
+interface RuntimeContext {
+    engine: AgentEngine;
+    model?: ModelConfig;
+    instructions?: string;
+    tools: EngineTool[];
+    skills: Map<string, Skill>;
+    thinkingLevel?: ThinkingLevel;
+    toolChoice?: ToolChoice;
+    env?: SessionEnv;
+    commands?: Command[];
+    sandboxTools?: (env: SessionEnv) => EngineTool[];
+    store: SessionStore;
+    bus: EventBus;
+    runId?: string;
+    agentName: string;
+    instanceId: string;
+    apiKey?: string;
+    /** Environment for provider credential resolution (threaded to the engine). */
+    envVars?: Record<string, unknown>;
+    /** Per-provider endpoint overrides (threaded to the engine). */
+    providers?: Record<string, {
+        baseUrl?: string;
+        headers?: Record<string, string>;
+        apiKey?: string;
+    }>;
+    compaction?: false | CompactionConfig;
+}
+interface CallOptions<TSchema extends GenericSchema = GenericSchema> {
+    result?: TSchema;
+    tools?: ToolDefinition[];
+    commands?: Command[];
+    model?: ModelConfig;
+    thinkingLevel?: ThinkingLevel;
+    toolChoice?: ToolChoice;
+    signal?: AbortSignal;
+    images?: PromptImage[];
+}
+interface Response<T = undefined> {
+    text: string;
+    data: T;
+    usage: Usage;
+}
+declare class Session {
+    #private;
+    readonly name: string;
+    readonly fs: AtlasFs;
+    constructor(name: string, ctx: RuntimeContext);
+    prompt(text: string, options?: CallOptions): CallHandle<Response>;
+    prompt<TSchema extends GenericSchema>(text: string, options: CallOptions<TSchema> & {
+        result: TSchema;
+    }): CallHandle<Response<InferOutput<TSchema>>>;
+    skill(ref: Skill | string, options?: CallOptions): CallHandle<Response<unknown>>;
+    task(text: string, options?: CallOptions): CallHandle<Response<unknown>>;
+    /** Branch this conversation: copy the current history into a new named session. */
+    fork(name: string): Promise<Session>;
+    shell(command: string, options?: {
+        cwd?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        commands?: Command[];
+    }): CallHandle<ShellResult>;
+    delete(): Promise<void>;
+    /** Manually compact this session's history, keeping the most recent messages. */
+    compact(keepRecent?: number): Promise<void>;
+}
+
+/**
+ * Harness — the runtime an agent uses. Owns sessions, an out-of-band
+ * filesystem, and a shell. Built by the runtime from an agent's config.
+ */
+
+declare class Harness {
+    #private;
+    readonly name: string;
+    readonly fs: AtlasFs;
+    constructor(name: string, ctx: RuntimeContext);
+    session(name?: string): Promise<Session>;
+    shell(command: string, options?: {
+        cwd?: string;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        commands?: Command[];
+    }): CallHandle<ShellResult>;
+}
+
+interface ToolApprovalRequest {
+    id: string;
+    baseId: string;
+    tool: string;
+    arguments: Record<string, unknown>;
+    reason?: string;
+    status: "pending" | "approved" | "rejected";
+    requestedAt: number;
+    decidedAt?: number;
+    consumedAt?: number;
+    resumeOnNextCall?: boolean;
+    note?: string;
+}
+interface ToolApprovalState {
+    kind: "tool_approval";
+    approvals: Record<string, ToolApprovalRequest>;
+    pending?: string;
+}
+declare class ToolApprovalRequiredError extends Error {
+    readonly runId: string;
+    readonly approval: ToolApprovalRequest;
+    code: string;
+    partialTranscript?: ToolApprovalPartialTranscript;
+    constructor(runId: string, approval: ToolApprovalRequest);
+}
+interface ToolApprovalPartialTranscript {
+    appended: Message[];
+    usage: Usage;
+}
+declare function isToolApprovalRequiredError(value: unknown): value is ToolApprovalRequiredError;
+
+/**
+ * pi-ai implementation of AgentEngine.
+ *
+ * THIS IS THE ONLY FILE THAT IMPORTS pi-ai. It runs a streaming tool-calling
+ * agentic loop over pi-ai's `stream()`. To swap pi-ai for our own loop, write
+ * another AgentEngine and change the one reference in runtime.ts.
+ *
+ * Supports: streaming (text/thinking deltas), extended thinking (mapped to the
+ * provider's reasoning effort), and prompt caching (cacheRetention + sessionId).
+ */
+
+declare class PiAgentEngine implements AgentEngine {
+    run(input: EngineRunInput, hooks: EngineHooks): Promise<EngineRunResult>;
+}
+/**
+ * Resolve the credential for a provider from an explicit env map. Known
+ * providers use their conventional variable; anything else falls back to
+ * `<PROVIDER>_API_KEY`.
+ */
+declare function envApiKeyFor(provider: string, env: Record<string, unknown> | undefined): string | undefined;
+declare class EngineError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+
+/**
+ * Cron triggers — a minimal 5-field cron matcher (minute hour day-of-month
+ * month day-of-week) plus the scheduler used by generated Node entries.
+ * Cloudflare entries instead export a `scheduled()` handler and let the
+ * platform fire it; both paths dispatch the same durable workflow runs.
+ *
+ * Supported syntax per field: asterisk, N, N-M, step suffixes (slash-S on a
+ * range or asterisk), and comma lists thereof. Names (JAN, MON) are not
+ * supported — use numbers.
+ */
+declare function cronMatches(expr: string, date: Date): boolean;
+interface CronJob {
+    /** 5-field cron expression (UTC). */
+    cron: string;
+    run: () => void | Promise<void>;
+}
+/**
+ * Start a minute-granularity scheduler (Node deploys). Fires each job whose
+ * expression matches the current UTC minute. Returns a stop function.
+ */
+declare function startCronScheduler(jobs: CronJob[], opts?: {
+    onError?: (err: unknown, job: CronJob) => void;
+}): () => void;
+
+/**
+ * Testing utilities.
+ *
+ * Design note: a programmatic, API-free way to test agents.
+ * `fakeEngine` is an AgentEngine you script with canned turns, so you can unit
+ * test agent wiring, tools, structured results, and events without a real
+ * model. Inject it via `invokeAgent({ ..., engine: fakeEngine(...) })`.
+ */
+
+interface FakeTurn {
+    text?: string;
+    toolCalls?: {
+        id?: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }[];
+}
+type FakeResponder = (input: EngineRunInput, turn: number) => FakeTurn;
+type AgentEvalSeverity = "gate" | "warn";
+interface AgentEvalExpect {
+    text?: string;
+    textIncludes?: string;
+    toolCalled?: string | string[];
+    noToolCalled?: string | string[];
+    toolResultIncludes?: string | string[] | Record<string, string>;
+}
+interface AgentEvalJudgeContext {
+    name: string;
+    agent: string;
+    message?: string;
+    payload?: unknown;
+    text: string;
+    runId: string;
+    events: Array<{
+        type?: string;
+        tool?: string;
+    }>;
+    toolResults: Array<{
+        tool: string;
+        text: string;
+    }>;
+}
+type AgentEvalJudgeResult = boolean | string | {
+    pass: boolean;
+    reason?: string;
+    score?: number;
+    metadata?: Record<string, unknown>;
+};
+type AgentEvalJudge = (ctx: AgentEvalJudgeContext) => AgentEvalJudgeResult | Promise<AgentEvalJudgeResult>;
+interface AgentEvalCase {
+    name?: string;
+    agent?: string;
+    message?: string;
+    payload?: unknown;
+    turns?: FakeTurn[];
+    expect?: AgentEvalExpect;
+    /**
+     * Optional semantic judge. Return true or { pass: true } to pass. Return
+     * false, a string reason, or { pass: false } to fail. Use this to call a
+     * hosted judge model or any team-specific scorer from the eval module.
+     */
+    judge?: AgentEvalJudge;
+    /** "gate" failures fail the command; "warn" failures are reported but non-blocking. */
+    severity?: AgentEvalSeverity;
+}
+interface AgentEvalDef extends AgentEvalCase {
+    /** Dataset fan-out: each case inherits top-level agent/message/turns/expect defaults. */
+    cases?: AgentEvalCase[];
+    /** Alias for cases, for teams that store external datasets. */
+    dataset?: AgentEvalCase[];
+}
+declare function defineEval(def: AgentEvalDef): AgentEvalDef;
+/** Build an AgentEngine that replays scripted turns (and runs real tools). */
+declare function fakeEngine(responder: FakeResponder): AgentEngine;
+interface SandboxConformanceOptions {
+    /** Stable session id passed to the SandboxFactory. */
+    id?: string;
+    /** Set false for providers that intentionally do not expose a POSIX shell. */
+    shell?: boolean;
+    /** Set false only while porting a provider that cannot enforce exec timeouts yet. */
+    timeout?: boolean;
+}
+/**
+ * Exercise the SessionEnv contract that built-in tools and context-pack mounts
+ * rely on. Connector packages can call this in their own tests to prove local,
+ * Docker, E2B, Daytona, Cloudflare, etc. behave the same at the AtlasFlow seam.
+ */
+declare function assertSandboxConformance(factory: SandboxFactory, options?: SandboxConformanceOptions): Promise<void>;
+
+export { AgentEngine, type AgentEvalCase, type AgentEvalDef, type AgentEvalExpect, type AgentEvalJudge, type AgentEvalJudgeContext, type AgentEvalJudgeResult, type AgentEvalSeverity, AgentHooks, AgentRuntimeConfig, AnyTool, AtlasFs, BUILTIN_TOOL_NAMES, type BashFactory, type BashLike, type BuiltinToolOptions, type CallHandle, type CallOptions, Command, CompactionConfig, CreatedAgent, type CronJob, type DiscoveredSessionContext, EngineError, EngineHooks, EngineRunInput, EngineRunResult, EngineTool, EventBus, type FakeResponder, type FakeTurn, Harness, type HttpConnectionMethod, type HttpConnectionOperation, type HttpConnectionOptions, type McpConnection, type McpServerOptions, type MemoryConnectorOptions, type MemorySearchParameters, MemorySearchParametersSchema, type MemorySearchResult, Message, ModelConfig, type PersonaBindingContext, type PersonaBindings, type PersonaManifest, PersonaManifestSchema, type PersonaSlot, type PersonaToolBindingResult, type PersonaToolsBinding, PiAgentEngine, PromptImage, RawTool, type ResolvedPersonaToolBindings, type Response, Rule, type RuleGuard, RuleViolation, type RuntimeContext, type SandboxConformanceOptions, SandboxFactory, SandboxNetworkPolicy, Session, SessionEnv, SessionStore, ShellResult, Skill, ThinkingLevel, type ToolApprovalRequest, ToolApprovalRequiredError, type ToolApprovalState, ToolChoice, ToolDefinition, Usage, type VirtualSandboxOptions, WorkflowDef, type WorkspaceSkill, assertSandboxConformance, bash, bashFactoryToSessionEnv, builtinTools, connectMcpServer, cronMatches, defineEval, defineHttpConnection, defineMemoryConnector, discoverSessionContext, envApiKeyFor, fakeEngine, isToolApprovalRequiredError, isWorkspaceSkill, loadWorkspaceSkill, makeCall, makeRuleGuard, parsePersonaManifest, parseSkillMarkdown, personaAgent, personaTriggers, personaWorkflowMounts, personaWorkflows, startCronScheduler, validateSlots, virtualSandbox };