octoflow-core 1.0.0

package/README.md

@@ -0,0 +1,272 @@
+# octoflow-core
+
+Main OctoFlow runtime for adding agents to existing TypeScript apps. It discovers ready LLM backends, routes requests, runs sessions, streams events, executes typed tools, applies policy, manages stores, and connects packs, flows, MCP servers, skills, gateways, memory, and plugins.
+
+Native CLI backends (`claude-code-cli`, `codex-cli`, `cursor-cli`, `gemini-cli`,
+`acp-cli`, and `custom`) are bridge-only: OctoFlow routes prompts and task
+state, while the CLI owns tools, MCP, skills, memory, and its native agent loop.
+Use API, SDK, local, or A2A backends when the OctoFlow core harness should own
+those capabilities.
+
+## Install
+
+```bash
+npm install octoflow-core
+```
+
+Node.js `>=20` is required.
+
+## Use It When
+
+- You want one API over CLI agents, API models, Ollama, custom hosts, or A2A peers.
+- You need request/response, streaming, sessions, resume, task state, and structured output in your own app.
+- You want built-in file and shell actions with approvals, path controls, profiles, and secret redaction.
+- You plan to add memory, MCP, skills, packs, flows, plugins, platform adapters, or an OpenAI-compatible gateway.
+
+## 30-Second Start
+
+```ts
+import { createAgent, defineAction, extractText } from 'octoflow-core';
+
+const lookupDocs = defineAction({
+  name: 'lookup_docs',
+  description: 'Look up project docs.',
+  parameters: {
+    type: 'object',
+    properties: { topic: { type: 'string' } },
+    required: ['topic'],
+  },
+  execute: async ({ topic }) => `Docs for ${String(topic)}`,
+});
+
+const agent = await createAgent({
+  llm: [
+    { backend: 'claude-code-cli', model: 'sonnet' },
+    { backend: 'anthropic-api', model: 'claude-sonnet-4-6' },
+    { provider: 'groq', model: 'llama-3.3-70b-versatile' },
+    { provider: 'openrouter', model: 'openai/gpt-4o-mini' },
+    { backend: 'gemini-api', model: 'gemini-2.5-flash' },
+    { backend: 'ollama', model: 'llama3.2' },
+  ],
+  actions: [lookupDocs],
+  context: { instructions: 'Use tools when they help.' },
+});
+
+const result = await agent.sendMessage({
+  message: 'Explain this repository in three bullets.',
+});
+
+console.log(extractText(result));
+await agent.close();
+```
+
+Backends without credentials or local binaries are skipped. The first ready entry in ordered `llm` fallback wins, with fallback on failure. Multiple provider profiles can share `openai-api`; each keeps isolated host/API-key/model config.
+
+Use `discoverAvailableBackends()` for zero-config readiness scans; with no explicit priority it checks the default routing order plus cataloged built-in backends such as Gemini CLI and ACP. Use `inspectBackendCatalog()` when tools, examples, or tests need the shared backend/provider list, auth env vars, default hosts, model override hints, and probe metadata without duplicating backend tables. Use `agent.inspectHarness()` after startup when diagnostics need the live inventory of selected backends, resolved config, plugins, registered actions/tools, runtime skills, `SKILL.md` bundles, MCP servers/tools, brain status, Pack workers, the canonical core capability matrix, and backend feature conformance.
+
+`createAgent()` is the single entry point for all runtimes. Use `agentType` to select the topology: `'tool-loop'` (default), `'supervisor'`, `'swarm'`, `'sequential'`, and more. First-use presets (`createCodingAgent()`, `createSupportAgent()`, `createResearchAgent()`, `createSecureToolAgent()`, `createSupervisorTeam()`) are thin wrappers over that same API. See [`docs/api.md#createagent-options`](../../docs/api.md#createagent-options) for the full option reference, and [`docs/agent-prompts.md`](../../docs/agent-prompts.md) for configuring the agent's base/system prompt and backend-native prompt caching.
+
+## What You Get
+
+| Area               | Runtime surface                                                                                                                                                                                                                                                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Backends           | Discovery, priority routing, explicit provider selection, CLI adapters (`claude-code-cli`, `codex-cli`, `gemini-cli`, `cursor-cli`), API providers (Anthropic, OpenAI, Gemini, Ollama), ACP — drive any [Agent Client Protocol](https://github.com/openclaw/acpx) agent (`acp-cli`, 16 built-in agents), custom hosts and CLIs. |
+| Conversations      | One-shot messages, streams, sessions, resume, default API compaction, backend-native prompt caching for stable prompt prefixes, provider cache diagnostics, task cost source/estimates, task state, stores, clean shutdown.                                                                                                     |
+| Tools              | `defineAction()`, built-ins, MCP loading, skills, custom action registry with opt-in strict duplicate mode for non-native-CLI harnesses. Native CLI backends keep their own tool/MCP/skill surface.                                                                                                                             |
+| Retrieval          | `chunkText()`, `createVectorStore()`, and `createRetrievalActions()` for simple embedder-backed file search/RAG in core.                                                                                                                                                                                                        |
+| Safety             | Approval flow, policy profiles, managed git worktrees, workspace-limited tools, path controls, tenant checks, deny paths, secret redaction, circuit breakers.                                                                                                                                                                   |
+| Orchestration      | Packs, flows, workers, topic channels, PackMesh, subagents, A2A JSON-RPC/SSE.                                                                                                                                                                                                                                                   |
+| Shipping           | OpenAI-compatible gateway, daemon mode, adapters, plugins, observability events.                                                                                                                                                                                                                                                |
+| Optional memory    | Attach local `octoflow-brain` or HTTP-backed `createRemoteBrain()` memory for the OctoFlow-owned harness; native CLI backends use their own memory/config surfaces.                                                                                                                                                             |
+| Optional sandboxes | Local sandbox profiles, managed per-request git worktrees, Docker, SSH, Vercel Sandbox, E2B, and custom execution environments.                                                                                                                                                                                                 |
+
+### ACP support
+
+Use `backend: 'acp-cli'` when you want one OctoFlow integration over multiple ACP-capable coding agents.
+
+- **Why users need it**: switch agent vendors without rewriting app glue code.
+- **What it gives users**: consistent `createAgent`/`sendMessage`/`stream` usage, bridge lifecycle events, and capability-aware ACP session handling while the ACP agent owns its native tools and MCP surface.
+- **DX behavior**: one-shot + streaming are the stable baseline; multi-turn persistence is enabled when the target ACP agent advertises `session/resume` or `session/load`.
+- **Runnable check**: `npm run backend-acp -w octoflow-examples` validates readiness, one-shot, stream, session continuity (or skip when unsupported), and steer-mode behavior.
+
+## Public Imports
+
+| Level        | Import                        | Use for                                                                                                                                        |
+| ------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Stable**   | `octoflow-core`               | **Canonical API.** Complete explicit public surface: app APIs, advanced extension APIs, migration tools, audits, and common runtime contracts. |
+| **Beta**     | `octoflow-core/pack`          | Pack and flow orchestration helpers, supervisor/worker factories.                                                                              |
+| **Beta**     | `octoflow-core/stores`        | Store implementations and contracts; in-memory and SQLite presets are stable through `createAgent` options.                                    |
+| **Beta**     | `octoflow-core/output`        | Structured output schema helpers and parsers.                                                                                                  |
+| **Preview**  | `octoflow-core/a2a`           | Agent-to-agent JSON-RPC/SSE client and server.                                                                                                 |
+| **Preview**  | `octoflow-core/environments`  | Execution environment implementations and contracts.                                                                                           |
+| **Preview**  | `octoflow-core/observability` | Event and telemetry helpers.                                                                                                                   |
+| **Internal** | `octoflow-core/testing`       | Test helpers for runtime behavior; not a product API.                                                                                          |
+
+The public API labels are documented in [`docs/api.md#stability-labels`](../../docs/api.md#stability-labels).
+
+## Common Recipes
+
+Stream live task updates:
+
+```ts
+for await (const event of agent.stream({
+  message: 'Draft release notes.',
+})) {
+  if (event.kind === 'artifact-update') {
+    const text = event.event.artifact.parts
+      .filter((part) => part.kind === 'text')
+      .map((part) => part.text)
+      .join('');
+    process.stdout.write(text);
+  }
+}
+```
+
+Set sandbox/worktree defaults once in `octoflow.config.json`:
+
+```json
+{
+  "priority": ["claude-code-cli", "codex-cli"],
+  "defaultProfile": "local-sandboxed",
+  "defaults": {
+    "worktree": {
+      "name": "fix-tests",
+      "cleanup": "never",
+      "reuse": true,
+      "dirty": "copy"
+    }
+  }
+}
+```
+
+Then a normal `agent.sendMessage({ message: 'Fix the failing tests.' })` runs
+with the configured sandbox profile and managed worktree. Per-call
+`worktree` still overrides config. `worktree: true` creates a detached checkout
+under `.octoflow/worktrees`; a string or `{ name }` controls the directory name. Use `dirty: "copy"` when the agent should see uncommitted local changes.
+
+Use `agent.runStream(...)` for orchestration progress (`flow-step-start`, `flow-step-complete`, `flow-terminated`, loop, and task-batch events). Use `onEvent` or `agent.onAny(...)` when you want those same run events on the shared event bus as `agent:flow-step-start`, `agent:flow-step-complete`, `agent:flow-terminated`, and the matching loop/task-batch names.
+
+```ts
+const agent = await createAgent({
+  onEvent(event) {
+    if (event.type === 'bridge:message') process.stdout.write(event.data.text);
+    if (event.type.startsWith('agent:flow-')) console.log(event.type);
+  },
+});
+```
+
+Expose a local HTTP endpoint for OpenAI or Anthropic-compatible clients:
+
+```ts
+const openAiGateway = await agent.makeGateway({ inboundProtocol: 'openai' });
+// Routes: /v1/models, /v1/chat/completions, /v1/responses, /v1/embeddings, /tools/invoke
+
+const anthropicGateway = await agent.makeGateway({
+  inboundProtocol: 'anthropic',
+});
+// Routes: /v1/models, /v1/messages
+```
+
+Expose an **AG-UI interoperable** SSE endpoint (CopilotKit, LangGraph, assistant-ui, CrewAI, Mastra):
+
+```ts
+import { createAgUiGatewayServer } from 'octoflow-core';
+
+const { server } = await createAgUiGatewayServer(agent);
+// Route: POST /agui/run  — SSE (default) or JSON (Accept: application/json)
+// Event taxonomy emitted per run (SSE order):
+//   RUN_STARTED → STATE_SNAPSHOT → STEP_STARTED → ACTIVITY_SNAPSHOT
+//   → ACTIVITY_DELTA → TEXT_MESSAGE_* → TOOL_CALL_* (+ TOOL_CALL_RESULT)
+//   → STATE_DELTA → MESSAGES_SNAPSHOT → STEP_FINISHED → CUSTOM → RUN_FINISHED
+// RunAgentInput: threadId, runId, messages, tools, context, forwardedProps, resume[], state.
+```
+
+Use the lifecycle verifier in your own tests:
+
+```ts
+import { verifyAgUiEventSequence } from 'octoflow-core';
+
+const violations = verifyAgUiEventSequence(events);
+// [] = conformant sequence; non-empty = lifecycle invariant broken
+```
+
+Full AG-UI support matrix: [`docs/feature-catalog.md`](../../docs/feature-catalog.md). Runnable references: [`react-ag-ui-chatbot`](../octoflow-examples/src/apps/app-react-ag-ui-chatbot/) for raw `@ag-ui/client`, and [`react-copilotkit-ag-ui-chatbot`](../octoflow-examples/src/apps/app-react-copilotkit-ag-ui-chatbot/) for CopilotKit UI on the same gateway.
+
+Enable persistent local state:
+
+```ts
+const agent = await createAgent({
+  priority: ['anthropic-api'],
+  storage: true,
+});
+```
+
+Call a remote agent over A2A (JSON-RPC + SSE, plus task push notification
+config set/get for webhook delivery):
+
+```ts
+import { A2AClient, createA2AServer } from 'octoflow-core/a2a';
+
+// Expose a local agent on http://127.0.0.1:4400/rpc
+const handle = await createA2AServer({
+  agent,
+  host: '127.0.0.1',
+  port: 4400,
+  agentCard: { name: 'release-notes', description: 'Drafts release notes.' },
+});
+handle.server.listen(4400, '127.0.0.1');
+
+// Call it from another process — one-shot, streaming, or session-scoped
+const client = new A2AClient({ url: 'http://127.0.0.1:4400/rpc' });
+const { text } = await client.run('Draft release notes for v1.4.');
+```
+
+Route tool execution to a sandboxed environment (Docker / SSH / Vercel Sandbox / E2B / local):
+
+```ts
+import {
+  createDockerEnvironment,
+  createEnvironmentsPlugin,
+} from 'octoflow-core/environments';
+
+const env = createDockerEnvironment({ image: 'node:20-alpine' });
+
+const agent = await createAgent({
+  plugins: [createEnvironmentsPlugin({ environments: { default: env } })],
+});
+// The plugin replaces the built-in `bash` action with one that delegates
+// to `env.exec(...)`, so shell calls run inside the container.
+```
+
+## Learn More
+
+- [`../../docs/api.md`](../../docs/api.md) - public API guide.
+- [`../../docs/ag-ui.md`](../../docs/ag-ui.md) - AG-UI gateway: DX, support matrix, React integration, and Mastra comparison.
+- [`../../docs/backend-integration.md`](../../docs/backend-integration.md) - backend setup and routing.
+- [`../../docs/configuration.md`](../../docs/configuration.md) - config files, profiles, env precedence, MCP, skills, tools.
+- [`../../docs/security.md`](../../docs/security.md) - approvals, sandboxing, credentials, and execution policy.
+- [`../octoflow-examples`](../octoflow-examples/README.md) - runnable templates.
+
+## File-size rule
+
+Per the root `AGENTS.md`, source files must stay ≤ 400 non-blank/non-comment lines.
+
+**Exemptions in this package:**
+
+| File           | Reason                                                                                                                                                                                                                                                    |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/index.ts` | Public barrel. Every export is an explicit named re-export — no logic, no wildcards. Line count grows with the public surface, not with implementation complexity. Splitting it would require wildcard exports (banned) or a redundant indirection layer. |
+
+All other files are subject to the 400-line limit. Split by concern when adding new exports.
+
+## Validate
+
+```bash
+npm run -w octoflow-core lint
+npm run -w octoflow-core typecheck
+npm run -w octoflow-core test
+```
+
+## Status
+
+**Beta.** `createAgent`, `defineAction`, stores, approvals, memory basics, and `agent.run({ flow })` are **Stable** — see [`docs/api.md#stability-labels`](../../docs/api.md#stability-labels) for the full stable surface and label definitions. Everything else is labeled **Beta**, **Preview**, or **Internal**. Pin versions before depending on it in production.

package/dist/__tests__/helpers/brain-contract.js

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import {
+  cognitiveMemoryFromCore,
+  MemoryCoreUnsupportedOperationError
+} from "../../runtime/bridge/brain-plugin.js";
+function runMemoryCoreContract(makeMemory) {
+  describe("MemoryCoreLike contract", () => {
+    it("remembers and recalls shaped memory records", async () => {
+      const memory = makeMemory();
+      const remembered = await memory.remember({
+        text: "Tenant billing exports require manager approval.",
+        kind: "fact",
+        source: "user"
+      });
+      expect(remembered.accepted).toBe(true);
+      if (!remembered.accepted) {
+        throw new Error("expected memory to be accepted");
+      }
+      expect(remembered.recordId).toEqual(expect.any(String));
+      const recalled = await memory.recall({
+        query: "billing exports approval",
+        topK: 3,
+        dryRead: true
+      });
+      expect(Array.isArray(recalled.items)).toBe(true);
+      expect(recalled.stats.candidateChunks).toBeGreaterThanOrEqual(0);
+      const first = recalled.items[0];
+      if (first) {
+        expect(typeof first.id).toBe("string");
+        expect(typeof first.score).toBe("number");
+        expect(typeof first.text).toBe("string");
+      }
+    });
+    it("adapts to CognitiveMemoryLike with explicit unsupported full operations", async () => {
+      const full = cognitiveMemoryFromCore(makeMemory());
+      await expect(full.digest()).rejects.toBeInstanceOf(
+        MemoryCoreUnsupportedOperationError
+      );
+      await expect(full.audit()).rejects.toBeInstanceOf(
+        MemoryCoreUnsupportedOperationError
+      );
+    });
+  });
+}
+function runCognitiveMemoryContract(makeBrain) {
+  runMemoryCoreContract(makeBrain);
+  describe("CognitiveMemoryLike contract", () => {
+    it("implements the full maintenance and feedback surface", async () => {
+      const brain = makeBrain();
+      const first = await brain.remember({
+        text: "Refund workflows use a 24 hour review SLA.",
+        kind: "fact",
+        source: "tool"
+      });
+      const second = await brain.remember({
+        text: "Refund workflows use an immediate auto-approval path.",
+        kind: "fact",
+        source: "external"
+      });
+      const digest = await brain.digest();
+      expect(digest.itemsCreated).toBeGreaterThanOrEqual(0);
+      expect(digest.hunchesUpdated).toBeGreaterThanOrEqual(0);
+      const consolidate = await brain.consolidate();
+      expect(consolidate.promoted).toBeGreaterThanOrEqual(0);
+      expect(consolidate.reinforced).toBeGreaterThanOrEqual(0);
+      expect(consolidate.demoted).toBeGreaterThanOrEqual(0);
+      expect(consolidate.quarantined).toBeGreaterThanOrEqual(0);
+      const feedback = await brain.feedback({
+        taskId: "contract-task",
+        outcome: "success",
+        summary: "Used refund workflow memory.",
+        relatedMemoryIds: first.accepted ? [first.recordId] : []
+      });
+      expect(typeof feedback.linked).toBe("boolean");
+      expect(feedback.updated).toBeGreaterThanOrEqual(0);
+      const contradiction = await brain.resolveContradiction({
+        memoryIdA: first.accepted ? first.recordId : "a",
+        memoryIdB: second.accepted ? second.recordId : "b",
+        resolution: "prefer_a"
+      });
+      expect(typeof contradiction.resolved).toBe("boolean");
+      expect(typeof contradiction.quarantined).toBe("boolean");
+      const audit = await brain.audit();
+      expect(audit.totalRecords).toBeGreaterThanOrEqual(0);
+      expect(audit.quarantineCount).toBeGreaterThanOrEqual(0);
+      const replay = await brain.replay(2);
+      expect(replay.failsReplayed).toBeGreaterThanOrEqual(0);
+      expect(replay.winsReplayed).toBeGreaterThanOrEqual(0);
+      expect(replay.explorationReplayed).toBeGreaterThanOrEqual(0);
+      const prune = await brain.prune({ statuses: ["stale", "archived"] });
+      expect(prune.pruned).toBeGreaterThanOrEqual(0);
+    });
+  });
+}
+export {
+  runCognitiveMemoryContract,
+  runMemoryCoreContract
+};
+//# sourceMappingURL=brain-contract.js.map

package/dist/__tests__/helpers/brain-contract.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/__tests__/helpers/brain-contract.ts"],
+  "sourcesContent": ["import { describe, expect, it } from 'vitest';\n\nimport type {\n  CognitiveMemoryLike,\n  MemoryCoreLike,\n} from '../../runtime/bridge/brain-plugin.js';\nimport {\n  cognitiveMemoryFromCore,\n  MemoryCoreUnsupportedOperationError,\n} from '../../runtime/bridge/brain-plugin.js';\n\nexport function runMemoryCoreContract(makeMemory: () => MemoryCoreLike): void {\n  describe('MemoryCoreLike contract', () => {\n    it('remembers and recalls shaped memory records', async () => {\n      const memory = makeMemory();\n      const remembered = await memory.remember({\n        text: 'Tenant billing exports require manager approval.',\n        kind: 'fact',\n        source: 'user',\n      });\n\n      expect(remembered.accepted).toBe(true);\n      if (!remembered.accepted) {\n        throw new Error('expected memory to be accepted');\n      }\n      expect(remembered.recordId).toEqual(expect.any(String));\n\n      const recalled = await memory.recall({\n        query: 'billing exports approval',\n        topK: 3,\n        dryRead: true,\n      });\n\n      expect(Array.isArray(recalled.items)).toBe(true);\n      expect(recalled.stats.candidateChunks).toBeGreaterThanOrEqual(0);\n      const first = recalled.items[0];\n      if (first) {\n        expect(typeof first.id).toBe('string');\n        expect(typeof first.score).toBe('number');\n        expect(typeof first.text).toBe('string');\n      }\n    });\n\n    it('adapts to CognitiveMemoryLike with explicit unsupported full operations', async () => {\n      const full = cognitiveMemoryFromCore(makeMemory());\n\n      await expect(full.digest()).rejects.toBeInstanceOf(\n        MemoryCoreUnsupportedOperationError\n      );\n      await expect(full.audit()).rejects.toBeInstanceOf(\n        MemoryCoreUnsupportedOperationError\n      );\n    });\n  });\n}\n\nexport function runCognitiveMemoryContract(\n  makeBrain: () => CognitiveMemoryLike\n): void {\n  runMemoryCoreContract(makeBrain);\n\n  describe('CognitiveMemoryLike contract', () => {\n    it('implements the full maintenance and feedback surface', async () => {\n      const brain = makeBrain();\n      const first = await brain.remember({\n        text: 'Refund workflows use a 24 hour review SLA.',\n        kind: 'fact',\n        source: 'tool',\n      });\n      const second = await brain.remember({\n        text: 'Refund workflows use an immediate auto-approval path.',\n        kind: 'fact',\n        source: 'external',\n      });\n\n      const digest = await brain.digest();\n      expect(digest.itemsCreated).toBeGreaterThanOrEqual(0);\n      expect(digest.hunchesUpdated).toBeGreaterThanOrEqual(0);\n\n      const consolidate = await brain.consolidate();\n      expect(consolidate.promoted).toBeGreaterThanOrEqual(0);\n      expect(consolidate.reinforced).toBeGreaterThanOrEqual(0);\n      expect(consolidate.demoted).toBeGreaterThanOrEqual(0);\n      expect(consolidate.quarantined).toBeGreaterThanOrEqual(0);\n\n      const feedback = await brain.feedback({\n        taskId: 'contract-task',\n        outcome: 'success',\n        summary: 'Used refund workflow memory.',\n        relatedMemoryIds: first.accepted ? [first.recordId] : [],\n      });\n      expect(typeof feedback.linked).toBe('boolean');\n      expect(feedback.updated).toBeGreaterThanOrEqual(0);\n\n      const contradiction = await brain.resolveContradiction({\n        memoryIdA: first.accepted ? first.recordId : 'a',\n        memoryIdB: second.accepted ? second.recordId : 'b',\n        resolution: 'prefer_a',\n      });\n      expect(typeof contradiction.resolved).toBe('boolean');\n      expect(typeof contradiction.quarantined).toBe('boolean');\n\n      const audit = await brain.audit();\n      expect(audit.totalRecords).toBeGreaterThanOrEqual(0);\n      expect(audit.quarantineCount).toBeGreaterThanOrEqual(0);\n\n      const replay = await brain.replay(2);\n      expect(replay.failsReplayed).toBeGreaterThanOrEqual(0);\n      expect(replay.winsReplayed).toBeGreaterThanOrEqual(0);\n      expect(replay.explorationReplayed).toBeGreaterThanOrEqual(0);\n\n      const prune = await brain.prune({ statuses: ['stale', 'archived'] });\n      expect(prune.pruned).toBeGreaterThanOrEqual(0);\n    });\n  });\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/actions/bridge-action-port.d.ts

@@ -0,0 +1,53 @@
+import type { LoginCallbacks, OAuthProviderId } from '../auth/types.js';
+export interface BridgeTopicPort {
+    emit(topic: string, payload: unknown, opts?: Record<string, unknown>): void;
+    subscribe(topic: string, handler: (event: unknown) => void | Promise<void>): () => void;
+    subscribePrefix(prefix: string, handler: (event: unknown) => void | Promise<void>): () => void;
+    waitFor(topic: string, opts?: Record<string, unknown>): Promise<unknown>;
+}
+export interface BridgeMeshMessage {
+    id: string;
+    from: string;
+    to: string;
+    payload: unknown;
+    replyTo?: string;
+    timestamp: number;
+}
+export interface BridgePackMeshPort {
+    request(from: string, to: string, payload: unknown, options?: {
+        timeoutMs?: number;
+    }): Promise<BridgeMeshMessage>;
+}
+/**
+ * Minimal interface declaring exactly the Bridge methods builtin actions need.
+ * Keeps the action layer decoupled from the full Bridge type while preserving
+ * compile-time safety — any method rename on Bridge breaks callers here.
+ */
+export interface BridgeActionPort {
+    readonly topics?: BridgeTopicPort;
+    readonly packMesh?: BridgePackMeshPort;
+    auth: {
+        login(provider: OAuthProviderId, callbacks: LoginCallbacks): Promise<{
+            expiresAt?: number;
+        }>;
+        logout(provider: string): Promise<void>;
+        getAuthStatus(provider?: string): Promise<unknown>;
+        refreshAuth(provider: string): Promise<{
+            expiresAt?: number;
+        }>;
+        isAuthenticated(provider: string): Promise<boolean>;
+    };
+    budget: {
+        checkBudget(contextId: string, tenant?: string): unknown;
+        getSpend(contextId: string): unknown;
+        updateBudget(scope: 'context' | 'tenant', newLimit: {
+            hardLimitUsd?: number;
+            softThresholdUsd?: number;
+        }): void;
+        resetBudget(contextId: string): void;
+    };
+    getTask(taskId: string): Promise<unknown>;
+    listTasks(opts: Record<string, unknown>): Promise<unknown>;
+    inspectBackends(): Promise<unknown>;
+}
+//# sourceMappingURL=bridge-action-port.d.ts.map

package/dist/actions/bridge-action-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-action-port.d.ts","sourceRoot":"","sources":["../../src/actions/bridge-action-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExE,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5E,SAAS,CACP,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAChD,MAAM,IAAI,CAAC;IACd,eAAe,CACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAChD,MAAM,IAAI,CAAC;IACd,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IACvC,IAAI,EAAE;QACJ,KAAK,CACH,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACnC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACxC,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QACnD,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC/D,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;KACrD,CAAC;IACF,MAAM,EAAE;QACN,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QACrC,YAAY,CACV,KAAK,EAAE,SAAS,GAAG,QAAQ,EAC3B,QAAQ,EAAE;YAAE,YAAY,CAAC,EAAE,MAAM,CAAC;YAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;SAAE,GAC7D,IAAI,CAAC;QACR,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KACtC,CAAC;IACF,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3D,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC"}

package/dist/actions/bridge-action-port.js

@@ -0,0 +1 @@
+//# sourceMappingURL=bridge-action-port.js.map

package/dist/actions/bridge-action-port.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/actions/builtin/args.d.ts

@@ -0,0 +1,6 @@
+export declare function optionalStringArg(args: Record<string, unknown>, key: string): string | undefined;
+export declare function requiredStringArg(args: Record<string, unknown>, key: string): string;
+export declare function optionalNumberArg(args: Record<string, unknown>, key: string): number | undefined;
+export declare function optionalStringArrayArg(args: Record<string, unknown>, key: string): string[] | undefined;
+export declare function optionalStringRecordArg(args: Record<string, unknown>, key: string): Record<string, string> | undefined;
+//# sourceMappingURL=args.d.ts.map

package/dist/actions/builtin/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/actions/builtin/args.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,GACV,MAAM,CAMR;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,GAAG,SAAS,CAMtB;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAUpC"}

package/dist/actions/builtin/args.js

@@ -0,0 +1,39 @@
+function optionalStringArg(args, key) {
+  const value = args[key];
+  return typeof value === "string" ? value : void 0;
+}
+function requiredStringArg(args, key) {
+  const value = optionalStringArg(args, key);
+  if (value === void 0) {
+    throw new TypeError(`Expected action argument "${key}" to be a string.`);
+  }
+  return value;
+}
+function optionalNumberArg(args, key) {
+  const value = args[key];
+  return typeof value === "number" ? value : void 0;
+}
+function optionalStringArrayArg(args, key) {
+  const value = args[key];
+  if (!Array.isArray(value)) return void 0;
+  return value.every((entry) => typeof entry === "string") ? [...value] : void 0;
+}
+function optionalStringRecordArg(args, key) {
+  const value = args[key];
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  const entries = Object.entries(value);
+  if (!entries.every(([, entry]) => typeof entry === "string")) {
+    return void 0;
+  }
+  return Object.fromEntries(entries);
+}
+export {
+  optionalNumberArg,
+  optionalStringArg,
+  optionalStringArrayArg,
+  optionalStringRecordArg,
+  requiredStringArg
+};
+//# sourceMappingURL=args.js.map

package/dist/actions/builtin/args.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/actions/builtin/args.ts"],
+  "sourcesContent": ["export function optionalStringArg(\n  args: Record<string, unknown>,\n  key: string\n): string | undefined {\n  const value = args[key];\n  return typeof value === 'string' ? value : undefined;\n}\n\nexport function requiredStringArg(\n  args: Record<string, unknown>,\n  key: string\n): string {\n  const value = optionalStringArg(args, key);\n  if (value === undefined) {\n    throw new TypeError(`Expected action argument \"${key}\" to be a string.`);\n  }\n  return value;\n}\n\nexport function optionalNumberArg(\n  args: Record<string, unknown>,\n  key: string\n): number | undefined {\n  const value = args[key];\n  return typeof value === 'number' ? value : undefined;\n}\n\nexport function optionalStringArrayArg(\n  args: Record<string, unknown>,\n  key: string\n): string[] | undefined {\n  const value = args[key];\n  if (!Array.isArray(value)) return undefined;\n  return value.every((entry) => typeof entry === 'string')\n    ? [...value]\n    : undefined;\n}\n\nexport function optionalStringRecordArg(\n  args: Record<string, unknown>,\n  key: string\n): Record<string, string> | undefined {\n  const value = args[key];\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    return undefined;\n  }\n  const entries = Object.entries(value);\n  if (!entries.every(([, entry]) => typeof entry === 'string')) {\n    return undefined;\n  }\n  return Object.fromEntries(entries);\n}\n"],
+  "mappings": "AAAO,SAAS,kBACd,MACA,KACoB;AACpB,QAAM,QAAQ,KAAK,GAAG;AACtB,SAAO,OAAO,UAAU,WAAW,QAAQ;AAC7C;AAEO,SAAS,kBACd,MACA,KACQ;AACR,QAAM,QAAQ,kBAAkB,MAAM,GAAG;AACzC,MAAI,UAAU,QAAW;AACvB,UAAM,IAAI,UAAU,6BAA6B,GAAG,mBAAmB;AAAA,EACzE;AACA,SAAO;AACT;AAEO,SAAS,kBACd,MACA,KACoB;AACpB,QAAM,QAAQ,KAAK,GAAG;AACtB,SAAO,OAAO,UAAU,WAAW,QAAQ;AAC7C;AAEO,SAAS,uBACd,MACA,KACsB;AACtB,QAAM,QAAQ,KAAK,GAAG;AACtB,MAAI,CAAC,MAAM,QAAQ,KAAK,EAAG,QAAO;AAClC,SAAO,MAAM,MAAM,CAAC,UAAU,OAAO,UAAU,QAAQ,IACnD,CAAC,GAAG,KAAK,IACT;AACN;AAEO,SAAS,wBACd,MACA,KACoC;AACpC,QAAM,QAAQ,KAAK,GAAG;AACtB,MAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,GAAG;AAC/D,WAAO;AAAA,EACT;AACA,QAAM,UAAU,OAAO,QAAQ,KAAK;AACpC,MAAI,CAAC,QAAQ,MAAM,CAAC,CAAC,EAAE,KAAK,MAAM,OAAO,UAAU,QAAQ,GAAG;AAC5D,WAAO;AAAA,EACT;AACA,SAAO,OAAO,YAAY,OAAO;AACnC;",
+  "names": []
+}

package/dist/actions/builtin/auth.d.ts

@@ -0,0 +1,3 @@
+import type { ActionDefinition } from '../types.js';
+export declare function createAuthActions(): ActionDefinition[];
+//# sourceMappingURL=auth.d.ts.map

package/dist/actions/builtin/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/actions/builtin/auth.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAepD,wBAAgB,iBAAiB,IAAI,gBAAgB,EAAE,CAsFtD"}

package/dist/actions/builtin/auth.js

@@ -0,0 +1,94 @@
+import { defineAction } from "../define.js";
+import { optionalStringArg, requiredStringArg } from "./args.js";
+const noopAuth = () => {
+};
+const OAUTH_PROVIDERS = ["anthropic", "openai", "copilot"];
+const PROVIDER_DISPLAY = {
+  anthropic: "Anthropic (Claude Max/Pro)",
+  openai: "OpenAI (ChatGPT Plus/Pro)",
+  copilot: "GitHub Copilot"
+};
+function createAuthActions() {
+  const loginActions = OAUTH_PROVIDERS.map(
+    (provider) => defineAction({
+      name: `auth_login_${provider}`,
+      description: `Authenticate with ${PROVIDER_DISPLAY[provider]} via OAuth. Call this when you receive an auth-required error for ${provider}.`,
+      parameters: { type: "object", properties: {} },
+      execute: async (_args, ctx) => {
+        const token = await ctx.bridge.auth.login(provider, {
+          onAuth: noopAuth,
+          onDeviceCode: noopAuth
+        });
+        return { authenticated: true, provider, expiresAt: token.expiresAt };
+      },
+      tags: ["auth", "builtin"]
+    })
+  );
+  return [
+    ...loginActions,
+    defineAction({
+      name: "auth_status",
+      description: "Check authentication status for all configured OAuth providers. Returns provider name, state (connected/disconnected/expired), and expiry time.",
+      parameters: {
+        type: "object",
+        properties: {
+          provider: {
+            type: "string",
+            description: "Optional: check a specific provider only (anthropic, openai, copilot)"
+          }
+        }
+      },
+      execute: async (args, ctx) => {
+        return ctx.bridge.auth.getAuthStatus(
+          optionalStringArg(args, "provider")
+        );
+      },
+      tags: ["auth", "builtin"]
+    }),
+    defineAction({
+      name: "auth_refresh",
+      description: "Refresh an expiring or expired OAuth token for a provider.",
+      parameters: {
+        type: "object",
+        properties: {
+          provider: {
+            type: "string",
+            description: "Provider to refresh (anthropic, openai, copilot)"
+          }
+        },
+        required: ["provider"]
+      },
+      execute: async (args, ctx) => {
+        const provider = requiredStringArg(args, "provider");
+        const token = await ctx.bridge.auth.refreshAuth(provider);
+        return { refreshed: true, provider, expiresAt: token.expiresAt };
+      },
+      tags: ["auth", "builtin"]
+    }),
+    defineAction({
+      name: "auth_logout",
+      description: "Log out from an OAuth provider and revoke the token.",
+      parameters: {
+        type: "object",
+        properties: {
+          provider: {
+            type: "string",
+            description: "Provider to log out from (anthropic, openai, copilot)"
+          }
+        },
+        required: ["provider"]
+      },
+      execute: async (args, ctx) => {
+        const provider = requiredStringArg(args, "provider");
+        await ctx.bridge.auth.logout(provider);
+        return { loggedOut: true, provider };
+      },
+      requireApproval: true,
+      tags: ["auth", "builtin", "destructive"]
+    })
+  ];
+}
+export {
+  createAuthActions
+};
+//# sourceMappingURL=auth.js.map