pulseed 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PulSeed Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,213 @@
-# pulseed
+<div align="center">
 
-AI agent orchestrator that gives existing agents the drive to persist.
+<img src="assets/seedy.png" alt="Seedy — PulSeed mascot" width="120" />
 
-> PulSeed sits above agents and drives them: selecting goals, spawning agent sessions, observing results, and judging completion. PulSeed doesn't think — it makes agents think.
+# PulSeed
 
-Full package coming soon.
+### Give your AI agents the drive to persist.
+
+[![Website](https://img.shields.io/badge/Website-pulseed.dev-blue)](https://pulseed.dev)
+[![CI](https://github.com/my-name-is-yu/PulSeed/actions/workflows/ci.yml/badge.svg)](https://github.com/my-name-is-yu/PulSeed/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/pulseed.svg)](https://www.npmjs.com/package/pulseed)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Set a goal. PulSeed observes the world, finds the gap, generates the next task, delegates it to any AI agent, verifies the result, and loops — until done.
+
+The project is documented for local use; follow the Quick Start steps to run PulSeed from source or as an installed CLI. For a guided walkthrough, see [Getting Started](docs/getting-started.md).
+
+<br/>
+</div>
+
+## Quick Start
+
+**1. Install PulSeed (Node.js 20+):**
+
+```bash
+npm install -g pulseed
+```
+
+**2. Set your API key:**
+
+```bash
+export OPENAI_API_KEY=sk-...
+
+# Or use Anthropic
+# export PULSEED_LLM_PROVIDER=anthropic
+# export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**3. Set a goal and run:**
+
+```bash
+pulseed goal add "Increase test coverage to 90%"
+pulseed run
+pulseed status
+```
+
+That's it. PulSeed assesses feasibility, decomposes the goal into measurable dimensions, delegates tasks to agents, and tracks progress automatically.
+
+> **Using OpenClaw?** Install the official plugin for seamless integration — see [`@pulseed/openclaw-plugin`](openclaw-plugin/README.md).
+
+## What is PulSeed?
+
+PulSeed is a **task discovery engine**. You give it a long-term goal — "double revenue in 6 months," "keep my dog healthy" — and it pursues it autonomously. It observes, calculates the gap, generates tasks, delegates to AI agents, and verifies results. Then it loops.
+
+**PulSeed doesn't execute. It orchestrates.** Every action is delegated to external agents (Claude Code, OpenAI Codex, Browser Use, or your own adapter). PulSeed's only direct operations are LLM calls for reasoning and state file read/write.
+
+**PulSeed knows when to stop.** It applies *satisficing* — when all goal dimensions cross their thresholds with sufficient evidence, the goal is complete. No runaway loops. No premature completion.
+
+## Why PulSeed?
+
+- **Execution boundary** — PulSeed never executes. It orchestrates and verifies. No runaway scripts.
+- **Goal-driven, not prompt-driven** — Set a long-term goal with measurable thresholds. PulSeed decomposes, delegates, observes, and loops.
+- **Satisficing** — Stops when "good enough." Prevents infinite loops and wasted compute.
+- **Asymmetric trust** — Failure costs 3x more than success rewards. Irreversible actions always require human approval.
+- **Agent-agnostic** — Works with any AI agent. Swap agents without changing goals.
+
+## Demos
+
+### Code Quality Goal
+
+> Goal = "Increase test coverage to 90% across the project"
+
+PulSeed observes current coverage, identifies untested modules, delegates test writing to a coding agent, and verifies results with actual test runs.
+
+See [docs/usecase.md](docs/usecase.md) for full walkthroughs · [Example goal config](docs/design/goal/goal-negotiation.md)
+
+### Revenue Target
+
+> Goal = "Double monthly revenue within 6 months"
+
+PulSeed tracks revenue metrics, identifies growth opportunities, delegates research and implementation tasks, and measures real outcomes.
+
+See [docs/usecase.md](docs/usecase.md) for full walkthroughs.
+
+### Health Monitoring
+
+> Goal = "Keep my dog healthy and happy"
+
+PulSeed monitors health indicators, schedules vet checkups, tracks nutrition, and escalates to you when human judgment is needed.
+
+See [docs/usecase.md](docs/usecase.md) for full walkthroughs.
+
+### OpenClaw Integration
+
+> "Migrate all source files from CommonJS to ESM with TypeScript"
+
+PulSeed detects the goal in your OpenClaw conversation, spawns agent sessions, tracks file-by-file migration progress, and auto-completes when done.
+
+See [docs/usecase.md](docs/usecase.md) for full walkthroughs.
+
+## How It Works
+
+The core loop runs at each goal node:
+
+```
+Observe → Gap → Score → Task → Execute → Verify → Loop
+```
+
+1. **Observe** — 3-layer evidence collection (mechanical checks, LLM review, self-report)
+2. **Gap** — quantify how far current state is from the goal threshold
+3. **Score** — prioritize by dissatisfaction, deadline urgency, and opportunity
+4. **Task** — LLM generates a concrete, verifiable task
+5. **Execute** — delegate to the selected agent adapter
+6. **Verify** — 3-layer result verification; pass, partial, or fail
+
+For detailed architecture, see [docs/architecture-map.md](docs/architecture-map.md).
+
+## Loop-Stall Prevention
+
+SeedPulse includes built-in stall detection to prevent loops from spinning without progress. When repeated cycles produce no measurable movement on a goal node, the orchestrator records the stall, changes the plan, and stops treating repetition as progress. See [Stall Detection Design](docs/design/core/stall-detection.md) for details.
+
+## Supported Adapters
+
+| Adapter | Type | Use Case |
+|---------|------|----------|
+| `openclaw_gateway` | OpenClaw Gateway | Goal detection, agent orchestration, progress tracking |
+| `claude_code_cli` | CLI | Code execution, file operations |
+| `openai_codex_cli` | CLI | Code execution, file operations |
+| `browser_use_cli` | CLI | Web browsing, scraping, form filling |
+| `claude_api` | LLM API | Text generation, analysis |
+| `github_issue` | REST API | Issue creation, search |
+| `a2a` | A2A Protocol | Remote agent delegation |
+
+Custom adapters can be added as [plugins](docs/design/infrastructure/plugin-development-guide.md) in `~/.pulseed/plugins/`.
+
+## Plugins & Integrations
+
+| Plugin | Description | Status |
+|--------|-------------|--------|
+| [`@pulseed/openclaw-plugin`](openclaw-plugin/) | OpenClaw Gateway — goal detection, agent orchestration, progress tracking | ✅ Stable |
+| [`@pulseed/slack-notifier`](plugins/slack-notifier/) | Slack notifications for goal events | ✅ Stable |
+
+See [Plugin Development Guide](docs/design/infrastructure/plugin-development-guide.md) for creating custom plugins.
+
+## Programmatic Usage
+
+```typescript
+import { CoreLoop, StateManager } from "pulseed";
+
+const stateManager = new StateManager("~/.pulseed");
+const loop = new CoreLoop({ stateManager, /* ...adapters */ });
+await loop.runOnce();
+```
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `pulseed goal add "<goal>"` | Negotiate and register a new goal |
+| `pulseed goal list` | List all goals with status |
+| `pulseed run` | Run one core loop iteration |
+| `pulseed status` | Show progress, gaps, trust scores |
+| `pulseed report` | Display latest report |
+| `pulseed cleanup` | Archive completed goals |
+| `pulseed datasource add/list/remove` | Manage data sources |
+
+## FAQ
+
+**How does PulSeed verify progress?**
+
+3-layer verification: mechanical checks (test results, file diffs, metrics) first, then independent LLM review, then executor self-report. Self-report alone caps progress at 70%.
+
+**Is it safe? Can it run dangerous commands?**
+
+Trust is asymmetric: failure costs -10, success only +3. Irreversible actions always require human approval regardless of trust level. Every goal also passes through an ethics gate before execution begins.
+
+**What happens when it gets stuck?**
+
+Stall detection uses four indicators. Responses are graduated: try a different approach, pivot strategy, then escalate to human. No infinite loops.
+
+**Can I use it for free?**
+
+Yes. PulSeed is open source and free. You only need an LLM API key (OpenAI or Anthropic).
+
+## Development
+
+```bash
+git clone https://github.com/my-name-is-yu/PulSeed.git
+cd PulSeed
+npm install
+npm run build
+npm test
+```
+
+State: `~/.pulseed/` · Reports: `~/.pulseed/reports/` · Ethics logs: `~/.pulseed/ethics/`
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+---
+
+PulSeed stores all state locally. No telemetry. No phone-home. Your LLM provider is the only external connection.
+
+[MIT License](LICENSE)
+
+---
+
+**Tell your agents what to achieve, not what to do.**

package/dist/adapter-layer.d.ts

@@ -0,0 +1,67 @@
+export interface AgentTask {
+    /** Session context + task instructions to pass to the agent */
+    prompt: string;
+    /** Timeout in milliseconds */
+    timeout_ms: number;
+    /** Which adapter to use for this task */
+    adapter_type: string;
+}
+export interface AgentResult {
+    /** Whether the task completed without error or timeout */
+    success: boolean;
+    /** stdout from CLI / LLM response text */
+    output: string;
+    /** stderr / error message, null on success */
+    error: string | null;
+    /** Process exit code for CLI adapters; null for API adapters */
+    exit_code: number | null;
+    /** Wall-clock time from execute() call to resolution, in milliseconds */
+    elapsed_ms: number;
+    /** How execution ended */
+    stopped_reason: "completed" | "timeout" | "error";
+    /**
+     * Whether the adapter actually modified any files, as detected by git diff --stat.
+     * undefined = check was not performed (e.g., not a git repo, or adapter skipped).
+     * true = files were changed; false = adapter reported success but no files changed.
+     */
+    filesChanged?: boolean;
+}
+export interface IAdapter {
+    execute(task: AgentTask): Promise<AgentResult>;
+    readonly adapterType: string;
+    readonly capabilities?: readonly string[];
+    /** Optional: return titles of existing tasks for dedup context injection into prompts. */
+    listExistingTasks?(): Promise<string[]>;
+    /** Optional: adapter-specific duplicate detection. Returns true if a duplicate exists. Fail-open: return false on error. */
+    checkDuplicate?(task: AgentTask): Promise<boolean>;
+}
+/**
+ * Registry that maps adapter type strings to IAdapter instances.
+ * AdapterRegistry itself is stateless beyond the map.
+ */
+export declare class AdapterRegistry {
+    private readonly adapters;
+    /**
+     * Register an adapter. Overwrites any previously registered adapter
+     * for the same adapterType.
+     */
+    register(adapter: IAdapter): void;
+    /**
+     * Retrieve an adapter by type string.
+     * Throws if no adapter is registered for that type.
+     */
+    getAdapter(type: string): IAdapter;
+    /**
+     * Returns a sorted list of all registered adapter type strings.
+     */
+    listAdapters(): string[];
+    /**
+     * Returns capabilities for all registered adapters.
+     * For adapters without capabilities defined, returns ["general_purpose"] as default.
+     */
+    getAdapterCapabilities(): Array<{
+        adapterType: string;
+        capabilities: string[];
+    }>;
+}
+//# sourceMappingURL=adapter-layer.d.ts.map

package/dist/adapter-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-layer.d.ts","sourceRoot":"","sources":["../src/adapter-layer.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gEAAgE;IAChE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,cAAc,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;IAClD;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAID,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,0FAA0F;IAC1F,iBAAiB,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,4HAA4H;IAC5H,cAAc,CAAC,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD;AAID;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAE7D;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI;IAIjC;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IAWlC;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE;IAIxB;;;OAGG;IACH,sBAAsB,IAAI,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAMjF"}

package/dist/adapter-layer.js

@@ -0,0 +1,50 @@
+// ─── AdapterLayer ───
+//
+// Defines the IAdapter interface, AgentTask/AgentResult types, and
+// AdapterRegistry for managing multiple adapter implementations.
+// This is the abstraction layer that isolates TaskLifecycle from
+// concrete agent implementations (Claude Code CLI, Claude API, etc.).
+// ─── AdapterRegistry ───
+/**
+ * Registry that maps adapter type strings to IAdapter instances.
+ * AdapterRegistry itself is stateless beyond the map.
+ */
+export class AdapterRegistry {
+    adapters = new Map();
+    /**
+     * Register an adapter. Overwrites any previously registered adapter
+     * for the same adapterType.
+     */
+    register(adapter) {
+        this.adapters.set(adapter.adapterType, adapter);
+    }
+    /**
+     * Retrieve an adapter by type string.
+     * Throws if no adapter is registered for that type.
+     */
+    getAdapter(type) {
+        const adapter = this.adapters.get(type);
+        if (!adapter) {
+            throw new Error(`AdapterRegistry: no adapter registered for type "${type}". ` +
+                `Available types: [${this.listAdapters().join(", ")}]`);
+        }
+        return adapter;
+    }
+    /**
+     * Returns a sorted list of all registered adapter type strings.
+     */
+    listAdapters() {
+        return Array.from(this.adapters.keys()).sort();
+    }
+    /**
+     * Returns capabilities for all registered adapters.
+     * For adapters without capabilities defined, returns ["general_purpose"] as default.
+     */
+    getAdapterCapabilities() {
+        return Array.from(this.adapters.entries()).map(([type, adapter]) => ({
+            adapterType: type,
+            capabilities: adapter.capabilities ? Array.from(adapter.capabilities) : ["general_purpose"],
+        }));
+    }
+}
+//# sourceMappingURL=adapter-layer.js.map

package/dist/adapter-layer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-layer.js","sourceRoot":"","sources":["../src/adapter-layer.ts"],"names":[],"mappings":"AAAA,uBAAuB;AACvB,EAAE;AACF,mEAAmE;AACnE,iEAAiE;AACjE,iEAAiE;AACjE,sEAAsE;AA8CtE,0BAA0B;AAE1B;;;GAGG;AACH,MAAM,OAAO,eAAe;IACT,QAAQ,GAA0B,IAAI,GAAG,EAAE,CAAC;IAE7D;;;OAGG;IACH,QAAQ,CAAC,OAAiB;QACxB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,IAAY;QACrB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,oDAAoD,IAAI,KAAK;gBAC3D,qBAAqB,IAAI,CAAC,YAAY,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACzD,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjD,CAAC;IAED;;;OAGG;IACH,sBAAsB;QACpB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;YACnE,WAAW,EAAE,IAAI;YACjB,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC;SAC5F,CAAC,CAAC,CAAC;IACN,CAAC;CACF"}

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

@@ -0,0 +1,49 @@
+import type { IAdapter, AgentTask, AgentResult } from "../execution/adapter-layer.js";
+import type { A2AClientConfig } from "./a2a-client.js";
+export interface A2AAdapterConfig extends A2AClientConfig {
+    /**
+     * Adapter type string registered in AdapterRegistry.
+     * Default: "a2a". Override to register multiple A2A agents
+     * (e.g., "a2a_research_agent", "a2a_code_agent").
+     */
+    adapterType?: string;
+    /**
+     * Override capabilities instead of deriving from Agent Card skills.
+     * If not set, capabilities are fetched from the Agent Card on first use.
+     */
+    capabilities?: string[];
+    /**
+     * Prefer SSE streaming over polling. Default: true.
+     * Falls back to polling if the agent does not advertise streaming support.
+     */
+    preferStreaming?: boolean;
+    /**
+     * Context ID for multi-turn conversations. If set, all tasks sent through
+     * this adapter share the same A2A conversation context.
+     */
+    contextId?: string;
+}
+export declare class A2AAdapter implements IAdapter {
+    readonly adapterType: string;
+    private readonly client;
+    private readonly preferStreaming;
+    private readonly contextId?;
+    private resolvedCapabilities;
+    private agentCard;
+    constructor(config: A2AAdapterConfig);
+    get capabilities(): readonly string[];
+    /**
+     * Fetch Agent Card and derive capabilities from skills.
+     * Called lazily on first execute() if capabilities were not provided in config.
+     * Safe to call multiple times (cached).
+     */
+    discoverCapabilities(): Promise<void>;
+    execute(task: AgentTask): Promise<AgentResult>;
+    private mapTaskToResult;
+    /**
+     * Extract text content from A2A artifacts and history.
+     * Concatenates all text parts from artifacts (preferred) or last agent message.
+     */
+    private extractTextOutput;
+}
+//# sourceMappingURL=a2a-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/a2a-adapter.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,WAAW,EACZ,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAMvD,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,qBAAa,UAAW,YAAW,QAAQ;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,oBAAoB,CAAkB;IAC9C,OAAO,CAAC,SAAS,CAA6B;gBAElC,MAAM,EAAE,gBAAgB;IAQpC,IAAI,YAAY,IAAI,SAAS,MAAM,EAAE,CAEpC;IAED;;;;OAIG;IACG,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC;IAcrC,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;IAsFpD,OAAO,CAAC,eAAe;IA2EvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CA+B1B"}

package/dist/adapters/a2a-adapter.js

@@ -0,0 +1,211 @@
+// ─── A2AAdapter ───
+//
+// IAdapter implementation for the Google A2A (Agent-to-Agent) Protocol v0.3.
+// Wraps A2AClient for network I/O and maps between PulSeed's AgentTask/AgentResult
+// and A2A's Message/Task types. Supports both polling and SSE streaming.
+import { randomUUID } from "node:crypto";
+import { A2AClient } from "./a2a-client.js";
+import { A2A_TERMINAL_STATES } from "../types/a2a.js";
+// ─── Adapter ───
+export class A2AAdapter {
+    adapterType;
+    client;
+    preferStreaming;
+    contextId;
+    resolvedCapabilities;
+    agentCard = null;
+    constructor(config) {
+        this.adapterType = config.adapterType ?? "a2a";
+        this.client = new A2AClient(config);
+        this.preferStreaming = config.preferStreaming ?? true;
+        this.contextId = config.contextId;
+        this.resolvedCapabilities = config.capabilities ?? null;
+    }
+    get capabilities() {
+        return this.resolvedCapabilities ?? ["general_purpose"];
+    }
+    /**
+     * Fetch Agent Card and derive capabilities from skills.
+     * Called lazily on first execute() if capabilities were not provided in config.
+     * Safe to call multiple times (cached).
+     */
+    async discoverCapabilities() {
+        if (this.agentCard)
+            return;
+        try {
+            this.agentCard = await this.client.fetchAgentCard();
+            if (!this.resolvedCapabilities && this.agentCard.skills?.length) {
+                this.resolvedCapabilities = this.agentCard.skills.flatMap((s) => s.tags ?? [s.id]);
+            }
+        }
+        catch {
+            // Agent Card not available — continue with default capabilities
+        }
+    }
+    async execute(task) {
+        const startedAt = Date.now();
+        // Lazy capability discovery
+        if (!this.agentCard) {
+            await this.discoverCapabilities();
+        }
+        // Build A2A message from PulSeed's prompt
+        const message = {
+            role: "user",
+            parts: [{ kind: "text", text: task.prompt }],
+            messageId: randomUUID(),
+            ...(this.contextId ? { contextId: this.contextId } : {}),
+        };
+        // Timeout via AbortController
+        const controller = new AbortController();
+        const timeoutHandle = setTimeout(() => controller.abort(), task.timeout_ms);
+        try {
+            let a2aTask;
+            const supportsStreaming = this.preferStreaming &&
+                this.agentCard?.capabilities?.streaming === true;
+            if (supportsStreaming) {
+                // ── SSE streaming path ──
+                a2aTask = await this.client.sendMessageStream(message, undefined, // onStatus callback — not needed for basic adapter
+                controller.signal);
+            }
+            else {
+                // ── Polling path ──
+                const initial = await this.client.sendMessage(message);
+                if (A2A_TERMINAL_STATES.has(initial.status.state)) {
+                    a2aTask = initial;
+                }
+                else {
+                    a2aTask = await this.client.waitForCompletion(initial.id, controller.signal);
+                }
+            }
+            clearTimeout(timeoutHandle);
+            return this.mapTaskToResult(a2aTask, startedAt);
+        }
+        catch (err) {
+            clearTimeout(timeoutHandle);
+            const elapsed = Date.now() - startedAt;
+            const errMessage = err instanceof Error ? err.message : String(err);
+            // Distinguish timeout from other errors
+            if (controller.signal.aborted ||
+                errMessage.includes("did not complete within")) {
+                return {
+                    success: false,
+                    output: "",
+                    error: `Timed out after ${task.timeout_ms}ms`,
+                    exit_code: null,
+                    elapsed_ms: elapsed,
+                    stopped_reason: "timeout",
+                };
+            }
+            return {
+                success: false,
+                output: "",
+                error: errMessage,
+                exit_code: null,
+                elapsed_ms: elapsed,
+                stopped_reason: "error",
+            };
+        }
+    }
+    // ─── Private: map A2A Task to PulSeed AgentResult ───
+    mapTaskToResult(task, startedAt) {
+        const elapsed = Date.now() - startedAt;
+        // Extract text output from artifacts
+        const output = this.extractTextOutput(task);
+        switch (task.status.state) {
+            case "completed":
+                return {
+                    success: true,
+                    output,
+                    error: null,
+                    exit_code: null,
+                    elapsed_ms: elapsed,
+                    stopped_reason: "completed",
+                };
+            case "failed":
+                return {
+                    success: false,
+                    output,
+                    error: task.status.message ?? "A2A task failed",
+                    exit_code: null,
+                    elapsed_ms: elapsed,
+                    stopped_reason: "error",
+                };
+            case "canceled":
+                return {
+                    success: false,
+                    output,
+                    error: "A2A task was canceled",
+                    exit_code: null,
+                    elapsed_ms: elapsed,
+                    stopped_reason: "timeout", // closest mapping
+                };
+            case "rejected":
+                return {
+                    success: false,
+                    output,
+                    error: task.status.message ??
+                        "A2A task was rejected by the remote agent",
+                    exit_code: null,
+                    elapsed_ms: elapsed,
+                    stopped_reason: "error",
+                };
+            case "input-required":
+            case "auth-required":
+                return {
+                    success: false,
+                    output,
+                    error: `A2A task requires ${task.status.state}: ${task.status.message ?? "no details"}. ` +
+                        "PulSeed does not support interactive input through adapters.",
+                    exit_code: null,
+                    elapsed_ms: elapsed,
+                    stopped_reason: "error",
+                };
+            default:
+                // Should not reach here after waitForCompletion, but handle gracefully
+                return {
+                    success: false,
+                    output,
+                    error: `A2A task in unexpected state: ${task.status.state}`,
+                    exit_code: null,
+                    elapsed_ms: elapsed,
+                    stopped_reason: "error",
+                };
+        }
+    }
+    /**
+     * Extract text content from A2A artifacts and history.
+     * Concatenates all text parts from artifacts (preferred) or last agent message.
+     */
+    extractTextOutput(task) {
+        // Prefer artifacts
+        if (task.artifacts?.length) {
+            const texts = [];
+            for (const artifact of task.artifacts) {
+                for (const part of artifact.parts) {
+                    if (part.kind === "text") {
+                        texts.push(part.text);
+                    }
+                }
+            }
+            if (texts.length > 0)
+                return texts.join("\n");
+        }
+        // Fallback: last agent message in history
+        if (task.history?.length) {
+            const agentMessages = task.history.filter((m) => m.role === "agent");
+            const last = agentMessages[agentMessages.length - 1];
+            if (last) {
+                const texts = [];
+                for (const part of last.parts) {
+                    if (part.kind === "text") {
+                        texts.push(part.text);
+                    }
+                }
+                if (texts.length > 0)
+                    return texts.join("\n");
+            }
+        }
+        return "";
+    }
+}
+//# sourceMappingURL=a2a-adapter.js.map

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

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

package/dist/adapters/a2a-client.d.ts

@@ -0,0 +1,28 @@
+import type { A2AAgentCard, A2ATask, A2ATaskState, A2AMessage } from "../types/a2a.js";
+export interface A2AClientConfig {
+    /** Base URL of the A2A agent (e.g. "https://agent.example.com") */
+    baseUrl: string;
+    /** Auth token (Bearer). Optional — depends on agent's securitySchemes. */
+    authToken?: string;
+    /** Polling interval when SSE is not supported. Default: 2000ms */
+    pollIntervalMs?: number;
+    /** Maximum total wait time for task completion. Default: 300_000ms (5 min) */
+    maxWaitMs?: number;
+}
+export declare class A2AClient {
+    private readonly baseUrl;
+    private readonly authToken?;
+    private readonly pollIntervalMs;
+    private readonly maxWaitMs;
+    constructor(config: A2AClientConfig);
+    fetchAgentCard(): Promise<A2AAgentCard>;
+    sendMessage(message: A2AMessage): Promise<A2ATask>;
+    getTask(taskId: string): Promise<A2ATask>;
+    cancelTask(taskId: string): Promise<void>;
+    waitForCompletion(taskId: string, signal?: AbortSignal): Promise<A2ATask>;
+    sendMessageStream(message: A2AMessage, onStatus?: (state: A2ATaskState, msg?: string) => void, signal?: AbortSignal): Promise<A2ATask>;
+    private buildHeaders;
+    private httpGet;
+    private jsonRpc;
+}
+//# sourceMappingURL=a2a-client.d.ts.map