pulseed 0.4.4 → 0.4.7

package/README.md

@@ -1,142 +1,70 @@
 <div align="center">
 
-<img src="assets/seedy.png" alt="Seedy — PulSeed mascot" width="120" />
+<img src="assets/seedy.png" alt="Seedy - PulSeed mascot" width="120" />
 
 # PulSeed
 
-### An AI agent system that grows your goals from seed to tree.
+Goal-driven orchestration for long-running work.
 
 [![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. Seedy takes it from there — observing, planning, delegating to AI agents, and tracking progress until it's done.
-
-<br/>
 </div>
 
-## What Can Seedy Do?
+PulSeed is an AI agent orchestrator for goals that need more than one chat turn.
 
-- **Track long-term goals with real measurable progress** — "Increase test coverage to 90%," "Double monthly revenue," "Keep my dog healthy." Seedy decomposes goals into dimensions, measures each one, and keeps going.
-- **Delegate work to any AI agent** — Claude Code, OpenAI Codex, Browser Use, or your own custom adapter. Swap agents without changing goals.
-- **Know when to stop** — Seedy applies satisficing: when every dimension crosses its threshold with enough evidence, the goal is complete. No infinite loops. No premature exits.
-- **Stay safe** — Irreversible actions always need your approval. Trust is asymmetric: one failure costs more than three successes earn.
+Naming note: `PulSeed` is the product name, and `pulseed` is the CLI and npm package name.
 
 ## Quick Start
 
-**1. Install PulSeed (Node.js 20+):**
+1. Install Node.js 20 or newer.
+2. Install the CLI:
 
 ```bash
 npm install -g pulseed
 ```
 
-**2. Set your API key:**
+3. Start PulSeed:
 
 ```bash
-export OPENAI_API_KEY=sk-...
-
-# Or use Anthropic
-# export PULSEED_LLM_PROVIDER=anthropic
-# export ANTHROPIC_API_KEY=sk-ant-...
+pulseed
 ```
 
-**3. Plant a goal and let Seedy grow it:**
-
-```bash
-pulseed goal add "Increase test coverage to 90%"
-pulseed run
-pulseed status
-```
-
-Seedy assesses feasibility, breaks the goal down, 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).
-
-## Demos
-
-**Code Quality** — "Increase test coverage to 90%." Seedy observes current coverage, identifies untested modules, delegates test writing to a coding agent, and verifies with real test runs.
-
-**Revenue Target** — "Double monthly revenue within 6 months." Seedy tracks revenue metrics, identifies growth opportunities, delegates research and implementation, and measures actual outcomes.
-
-**Health Monitoring** — "Keep my dog healthy." Seedy monitors health indicators, schedules vet checkups, tracks nutrition, and escalates when human judgment is needed.
-
-More examples in [docs/usecase.md](docs/usecase.md).
-
-## Features
+Then describe what you want in natural language, such as "Increase test coverage to 90%."
 
-- **Goal-driven orchestration** — Set a destination, not step-by-step instructions
-- **Agent-agnostic** — Swap agents without changing goals
-- **Satisficing** — Knows when "good enough" is enough
-- **Asymmetric trust** — Failure costs more than success; safety by default
-- **Stall detection** — Detects loops and changes strategy automatically
-- **Plugin system** — Extend with custom adapters, notifiers, and data sources
-- **Goal trees** — Decompose large goals into sub-goals, each tracked independently
-- **TUI dashboard** — Real-time terminal UI with progress, logs, and approval flow
+## Current Architecture
 
-Deep dive: [Architecture Map](docs/architecture-map.md) | [How it works](docs/mechanism.md)
+PulSeed uses two layers:
 
-## Adapters
+- `CoreLoop` keeps a goal moving, checks progress, and decides whether to continue, refine, verify, or stop
+- `AgentLoop` handles bounded tool-using work such as task execution, chat turns, and selected runtime phases
 
-| Adapter | Type | Use Case |
-|---------|------|----------|
-| `openclaw_gateway` | OpenClaw Gateway | Goal detection, agent orchestration |
-| `claude_code_cli` | CLI | Code execution, file operations |
-| `openai_codex_cli` | CLI | Code execution, file operations |
-| `browser_use_cli` | CLI | Web browsing, scraping |
-| `claude_api` | LLM API | Text generation, analysis |
-| `github_issue` | REST API | Issue creation, search |
-| `a2a` | A2A Protocol | Remote agent delegation |
+State, reports, schedules, and local memory live under `~/.pulseed/`.
 
-Custom adapters: [Plugin Development Guide](docs/design/infrastructure/plugin-development-guide.md)
+Security boundary: PulSeed uses approval gates and verification around delegated work,
+but it does not provide OS-level sandboxing for agent subprocesses. For high-risk or
+untrusted goals, run PulSeed inside a container or VM. See [Security](SECURITY.md).
 
-## Plugins
-
-| Plugin | Description |
-|--------|-------------|
-| [`@pulseed/openclaw-plugin`](openclaw-plugin/) | OpenClaw Gateway — goal detection, agent orchestration, progress tracking |
-| [`@pulseed/slack-notifier`](plugins/slack-notifier/) | Slack notifications for goal events |
-
-## Getting Started (Developers)
-
-**Programmatic usage:**
-
-```typescript
-import { CoreLoop, StateManager } from "pulseed";
-
-const stateManager = new StateManager("~/.pulseed");
-const loop = new CoreLoop({ stateManager, /* ...adapters */ });
-await loop.runOnce();
-```
-
-**CLI reference:** See [docs/getting-started.md](docs/getting-started.md) for the full command list.
-
-**Development setup:**
+## Main Command
 
 ```bash
-git clone https://github.com/my-name-is-yu/PulSeed.git
-cd PulSeed
-npm install
-npm run build
-npm test
+pulseed
 ```
 
-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 is designed so the primary workflow can happen through natural language.
+Use the lower-level CLI commands only when you need scriptable or diagnostic control.
 
-PulSeed stores all state locally. No telemetry. No phone-home. Your LLM provider is the only external connection.
+## Docs
 
-[MIT License](LICENSE)
+- [Getting Started](docs/getting-started.md)
+- [Docs Index](docs/index.md)
+- [Mechanism](docs/mechanism.md)
+- [Runtime](docs/runtime.md)
+- [Configuration](docs/configuration.md)
+- [Architecture Map](docs/architecture-map.md)
 
----
+## License
 
-**Plant the seed. Watch it grow.**
+MIT

package/dist/adapters/agents/native-agent-loop.d.ts

@@ -0,0 +1,7 @@
+import type { AgentTask, AgentResult, IAdapter } from "../../orchestrator/execution/adapter-layer.js";
+export declare class NativeAgentLoopAdapter implements IAdapter {
+    readonly adapterType = "agent_loop";
+    readonly capabilities: readonly ["general_purpose", "tool_calling", "native_agentloop"];
+    execute(_task: AgentTask): Promise<AgentResult>;
+}
+//# sourceMappingURL=native-agent-loop.d.ts.map

package/dist/adapters/agents/native-agent-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-agent-loop.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/native-agent-loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AAEtG,qBAAa,sBAAuB,YAAW,QAAQ;IACrD,QAAQ,CAAC,WAAW,gBAAgB;IACpC,QAAQ,CAAC,YAAY,mEAIV;IAEL,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;CAUtD"}

package/dist/adapters/agents/native-agent-loop.js

@@ -0,0 +1,19 @@
+export class NativeAgentLoopAdapter {
+    adapterType = "agent_loop";
+    capabilities = [
+        "general_purpose",
+        "tool_calling",
+        "native_agentloop",
+    ];
+    async execute(_task) {
+        return {
+            success: false,
+            output: "",
+            error: "NativeAgentLoopAdapter is a selection marker. TaskLifecycle must execute via TaskAgentLoopRunner.",
+            exit_code: null,
+            elapsed_ms: 0,
+            stopped_reason: "error",
+        };
+    }
+}
+//# sourceMappingURL=native-agent-loop.js.map

package/dist/adapters/agents/native-agent-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-agent-loop.js","sourceRoot":"","sources":["../../../src/adapters/agents/native-agent-loop.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,sBAAsB;IACxB,WAAW,GAAG,YAAY,CAAC;IAC3B,YAAY,GAAG;QACtB,iBAAiB;QACjB,cAAc;QACd,kBAAkB;KACV,CAAC;IAEX,KAAK,CAAC,OAAO,CAAC,KAAgB;QAC5B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,EAAE;YACV,KAAK,EAAE,mGAAmG;YAC1G,SAAS,EAAE,IAAI;YACf,UAAU,EAAE,CAAC;YACb,cAAc,EAAE,OAAO;SACxB,CAAC;IACJ,CAAC;CACF"}

package/dist/adapters/agents/openai-codex.d.ts

@@ -13,6 +13,8 @@ export interface OpenAICodexCLIAdapterConfig {
     model?: string;
     /** Repository path passed to Codex for workspace-aware execution. Default: "." */
     repoPath?: string;
+    /** Pass --skip-git-repo-check. Default: true for daemon/test workspaces. */
+    skipGitRepoCheck?: boolean;
 }
 export declare class OpenAICodexCLIAdapter implements IAdapter {
     readonly adapterType = "openai_codex_cli";
@@ -21,6 +23,7 @@ export declare class OpenAICodexCLIAdapter implements IAdapter {
     private readonly sandboxPolicy;
     private readonly model;
     private readonly repoPath;
+    private readonly skipGitRepoCheck;
     private readonly logger?;
     constructor(config?: OpenAICodexCLIAdapterConfig, logger?: Logger);
     execute(task: AgentTask): Promise<AgentResult>;

package/dist/adapters/agents/openai-codex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai-codex.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/openai-codex.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,+CAA+C,CAAC;AACtG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,MAAM,WAAW,2BAA2B;IAC1C,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,qBAAsB,YAAW,QAAQ;IACpD,QAAQ,CAAC,WAAW,sBAAsB;IAC1C,QAAQ,CAAC,YAAY,yEAA0E;IAE/F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;gBAErB,MAAM,GAAE,2BAAgC,EAAE,MAAM,CAAC,EAAE,MAAM;IAS/D,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;CA2CrD"}
+{"version":3,"file":"openai-codex.d.ts","sourceRoot":"","sources":["../../../src/adapters/agents/openai-codex.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,+CAA+C,CAAC;AACtG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAGtD,MAAM,WAAW,2BAA2B;IAC1C,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,qBAAa,qBAAsB,YAAW,QAAQ;IACpD,QAAQ,CAAC,WAAW,sBAAsB;IAC1C,QAAQ,CAAC,YAAY,yEAA0E;IAE/F,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;gBAErB,MAAM,GAAE,2BAAgC,EAAE,MAAM,CAAC,EAAE,MAAM;IAU/D,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;CA+CrD"}

package/dist/adapters/agents/openai-codex.js

@@ -12,7 +12,8 @@
 //   - `-s danger-full-access` sets sandbox policy to allow full disk/command access
 //   - `-m <model>` selects the model (e.g. "o4-mini", "o3")
 //   - When [PROMPT] arg is omitted (or `-` is given), prompt is read from stdin
-//   - NOTE: --full-auto does NOT exist in this version; use sandbox policy instead
+//   - --skip-git-repo-check allows execution in temporary/synced worktrees that
+//     are not in Codex's trusted directory list.
 import { spawnWithTimeout, spawnResultToAgentResult } from "../spawn-helper.js";
 export class OpenAICodexCLIAdapter {
     adapterType = "openai_codex_cli";
@@ -21,6 +22,7 @@ export class OpenAICodexCLIAdapter {
     sandboxPolicy;
     model;
     repoPath;
+    skipGitRepoCheck;
     logger;
     constructor(config = {}, logger) {
         this.cliPath = config.cliPath ?? "codex";
@@ -28,6 +30,7 @@ export class OpenAICodexCLIAdapter {
             config.sandboxPolicy !== undefined ? config.sandboxPolicy : "danger-full-access";
         this.model = config.model;
         this.repoPath = config.repoPath?.trim() || ".";
+        this.skipGitRepoCheck = config.skipGitRepoCheck ?? true;
         this.logger = logger;
     }
     async execute(task) {
@@ -41,6 +44,9 @@ export class OpenAICodexCLIAdapter {
         if (this.model) {
             spawnArgs.push("-m", this.model);
         }
+        if (this.skipGitRepoCheck) {
+            spawnArgs.push("--skip-git-repo-check");
+        }
         // allowed_tools: codex-cli does not have a native tool-restriction flag.
         // Log a warning for observability; toolset constraint is enforced at the
         // PulSeed layer (ToolsetLock) rather than being delegated to the CLI.

package/dist/adapters/agents/openai-codex.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai-codex.js","sourceRoot":"","sources":["../../../src/adapters/agents/openai-codex.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,EAAE;AACF,+DAA+D;AAC/D,yEAAyE;AACzE,iDAAiD;AACjD,uEAAuE;AACvE,EAAE;AACF,yEAAyE;AACzE,EAAE;AACF,sCAAsC;AACtC,+DAA+D;AAC/D,oFAAoF;AACpF,4DAA4D;AAC5D,gFAAgF;AAChF,mFAAmF;AAInF,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAiBhF,MAAM,OAAO,qBAAqB;IACvB,WAAW,GAAG,kBAAkB,CAAC;IACjC,YAAY,GAAG,CAAC,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,CAAU,CAAC;IAE9E,OAAO,CAAS;IAChB,aAAa,CAAgB;IAC7B,KAAK,CAAqB;IAC1B,QAAQ,CAAS;IACjB,MAAM,CAAU;IAEjC,YAAY,SAAsC,EAAE,EAAE,MAAe;QACnE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC;QACzC,IAAI,CAAC,aAAa;YAChB,MAAM,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,oBAAoB,CAAC;QACnF,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC;QAC/C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAe;QAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,uDAAuD;QACvD,gFAAgF;QAChF,MAAM,SAAS,GAAa,CAAC,MAAM,CAAC,CAAC;QAErC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;QAC3C,CAAC;QAED,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACnC,CAAC;QAED,yEAAyE;QACzE,yEAAyE;QACzE,sEAAsE;QACtE,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,8EAA8E;gBAC5E,iEAAiE,EACnE,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CACtC,CAAC;QACJ,CAAC;QAED,sEAAsE;QACtE,oGAAoG;QACpG,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC;QACtC,MAAM,MAAM,GAAG,MAAM,gBAAgB,CACnC,IAAI,CAAC,OAAO,EACZ,SAAS,EACT,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;EACjG,IAAI,CAAC,aAAa;;;EAGlB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,EACzB,IAAI,CAAC,UAAU,CAChB,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QACvC,OAAO,wBAAwB,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACpE,CAAC;CACF"}
+{"version":3,"file":"openai-codex.js","sourceRoot":"","sources":["../../../src/adapters/agents/openai-codex.ts"],"names":[],"mappings":"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"}

package/dist/adapters/datasources/github-issue-datasource.d.ts

@@ -20,6 +20,8 @@ export declare class GitHubIssueDataSourceAdapter implements IDataSourceAdapter
     healthCheck(): Promise<boolean>;
     private resolveRepo;
     private resolveLabel;
+    private resolveQueryContext;
+    private resolveQueryPlan;
     /**
      * Spawn `gh issue list` for a single state and call back with results.
      * Uses a callback so the result can be returned synchronously inside
@@ -38,6 +40,17 @@ export declare class GitHubIssueDataSourceAdapter implements IDataSourceAdapter
      * microtask gaps.
      */
     private spawnList;
+    private createListProcess;
+    private buildCountResult;
+    private createSingleStateResultBuilder;
+    private createAggregateResultBuilder;
+    private buildSingleStateResult;
+    private buildAggregateResult;
+    private buildErrorResult;
+    private buildMetricResult;
+    private buildUnknownDimensionResult;
+    private buildCompletionMetadata;
+    private buildAggregateMetrics;
     private buildListArgs;
     private parseIssueList;
 }

package/dist/adapters/datasources/github-issue-datasource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"github-issue-datasource.d.ts","sourceRoot":"","sources":["../../../src/adapters/datasources/github-issue-datasource.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mDAAmD,CAAC;AAC5F,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,iCAAiC,CAAC;AAIzC,UAAU,kBAAmB,SAAQ,gBAAgB;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAcD,qBAAa,4BAA6B,YAAW,kBAAkB;IACrE,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAY;IAC/C,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAE,MAAa;IAK3D,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAoH3D,sBAAsB,IAAI,MAAM,EAAE;IAI5B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAoC/B,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,YAAY;IAKpB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAgDrB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IA6BvB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IA8CjB,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,cAAc;CAWvB"}
+{"version":3,"file":"github-issue-datasource.d.ts","sourceRoot":"","sources":["../../../src/adapters/datasources/github-issue-datasource.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mDAAmD,CAAC;AAC5F,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EACjB,MAAM,iCAAiC,CAAC;AAIzC,UAAU,kBAAmB,SAAQ,gBAAgB;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAkBD,qBAAa,4BAA6B,YAAW,kBAAkB;IACrE,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAY;IAC/C,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,EAAE,gBAAgB,EAAE,MAAM,GAAE,MAAa;IAK3D,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0B3D,sBAAsB,IAAI,MAAM,EAAE;IAI5B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAoC/B,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,mBAAmB;IAyB3B,OAAO,CAAC,gBAAgB;IAcxB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAcrB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IA6BvB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IA4CjB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,8BAA8B;IAMtC,OAAO,CAAC,4BAA4B;IAQpC,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,oBAAoB;IAyB5B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,2BAA2B;IASnC,OAAO,CAAC,uBAAuB;IAc/B,OAAO,CAAC,qBAAqB;IAsB7B,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,cAAc;CAWvB"}

package/dist/adapters/datasources/github-issue-datasource.js

@@ -32,110 +32,15 @@ export class GitHubIssueDataSourceAdapter {
         // No-op network validation — gh CLI availability is checked at query/healthCheck time.
     }
     query(params) {
-        const config = this.config;
-        const repo = this.resolveRepo(config);
-        const label = this.resolveLabel(config);
-        const timeoutMs = params.timeout_ms ?? 10_000;
-        const sourceId = this.sourceId;
-        // Check dimension_mapping for redirect
-        const dimMapping = config.dimension_mapping ?? {};
-        const dimension = params.expression ?? params.dimension_name;
-        const resolvedDimension = dimMapping[dimension] ?? dimension;
-        // Unknown dimension — return immediately without spawning
-        const knownDimensions = new Set([
-            "open_issue_count",
-            "closed_issue_count",
-            "total_issue_count",
-            "completion_ratio",
-        ]);
-        if (!knownDimensions.has(resolvedDimension)) {
-            return Promise.resolve({
-                value: null,
-                raw: [],
-                timestamp: new Date().toISOString(),
-                source_id: sourceId,
-            });
+        const { repo, label, timeoutMs, resolvedDimension, sourceId } = this.resolveQueryContext(params);
+        const queryPlan = this.resolveQueryPlan(resolvedDimension);
+        if (queryPlan === null) {
+            return Promise.resolve(this.buildUnknownDimensionResult(sourceId));
         }
-        // ── Dimensions that require only open issues ──────────────────────────
-        if (resolvedDimension === "open_issue_count") {
-            return this.queryOneState("open", repo, label, timeoutMs, (openIssues, err) => {
-                if (err !== null) {
-                    return {
-                        value: null,
-                        raw: [],
-                        timestamp: new Date().toISOString(),
-                        source_id: sourceId,
-                        error: err,
-                    };
-                }
-                return {
-                    value: openIssues.length,
-                    raw: openIssues,
-                    timestamp: new Date().toISOString(),
-                    source_id: sourceId,
-                };
-            });
+        if (queryPlan.kind === "single") {
+            return this.queryOneState(queryPlan.state, repo, label, timeoutMs, this.createSingleStateResultBuilder(sourceId));
         }
-        if (resolvedDimension === "closed_issue_count") {
-            return this.queryOneState("closed", repo, label, timeoutMs, (closedIssues, err) => {
-                if (err !== null) {
-                    return {
-                        value: null,
-                        raw: [],
-                        timestamp: new Date().toISOString(),
-                        source_id: sourceId,
-                        error: err,
-                    };
-                }
-                return {
-                    value: closedIssues.length,
-                    raw: closedIssues,
-                    timestamp: new Date().toISOString(),
-                    source_id: sourceId,
-                };
-            });
-        }
-        // ── Dimensions that require both open and closed issues ───────────────
-        // (completion_ratio, total_issue_count)
-        return this.queryBothStates(repo, label, timeoutMs, (openIssues, closedIssues, err) => {
-            if (err !== null) {
-                return {
-                    value: null,
-                    raw: [],
-                    timestamp: new Date().toISOString(),
-                    source_id: sourceId,
-                    error: err,
-                };
-            }
-            const openCount = openIssues.length;
-            const closedCount = closedIssues.length;
-            const totalCount = openCount + closedCount;
-            const completionRatio = totalCount === 0 ? 0 : closedCount / totalCount;
-            const allIssues = [...openIssues, ...closedIssues];
-            let value;
-            switch (resolvedDimension) {
-                case "total_issue_count":
-                    value = totalCount;
-                    break;
-                case "completion_ratio":
-                    value = completionRatio;
-                    break;
-                default:
-                    value = 0;
-            }
-            return {
-                value,
-                raw: allIssues,
-                timestamp: new Date().toISOString(),
-                source_id: sourceId,
-                metadata: {
-                    open_count: openCount,
-                    closed_count: closedCount,
-                    total_count: totalCount,
-                    completion_ratio: completionRatio,
-                },
-            };
-        });
+        return this.queryBothStates(repo, label, timeoutMs, this.createAggregateResultBuilder(sourceId, queryPlan.dimension));
     }
     getSupportedDimensions() {
         return ["open_issue_count", "closed_issue_count", "total_issue_count", "completion_ratio"];
@@ -190,6 +95,36 @@ export class GitHubIssueDataSourceAdapter {
         const mapping = config.dimension_mapping ?? {};
         return mapping["_label"] ?? "pulseed";
     }
+    resolveQueryContext(params) {
+        const config = this.config;
+        const repo = this.resolveRepo(config);
+        const label = this.resolveLabel(config);
+        const timeoutMs = params.timeout_ms ?? 10_000;
+        const sourceId = this.sourceId;
+        const dimMapping = config.dimension_mapping ?? {};
+        const dimension = params.expression ?? params.dimension_name;
+        const resolvedDimension = dimMapping[dimension] ?? dimension;
+        return {
+            repo,
+            label,
+            timeoutMs,
+            resolvedDimension,
+            sourceId,
+        };
+    }
+    resolveQueryPlan(resolvedDimension) {
+        switch (resolvedDimension) {
+            case "open_issue_count":
+                return { kind: "single", state: "open" };
+            case "closed_issue_count":
+                return { kind: "single", state: "closed" };
+            case "total_issue_count":
+            case "completion_ratio":
+                return { kind: "aggregate", dimension: resolvedDimension };
+            default:
+                return null;
+        }
+    }
     /**
      * Spawn `gh issue list` for a single state and call back with results.
      * Uses a callback so the result can be returned synchronously inside
@@ -197,36 +132,8 @@ export class GitHubIssueDataSourceAdapter {
      */
     queryOneState(state, repo, label, timeoutMs, cb) {
         return new Promise((resolve) => {
-            let stdout = "";
-            let stderr = "";
-            let timedOut = false;
-            const args = this.buildListArgs(state, repo, label);
-            const child = spawn(this.ghPath, args, { stdio: ["ignore", "pipe", "pipe"] });
-            const timeoutHandle = setTimeout(() => {
-                timedOut = true;
-                child.kill("SIGTERM");
-            }, timeoutMs);
-            child.stdout.on("data", (chunk) => {
-                stdout += chunk.toString("utf8");
-            });
-            child.stderr.on("data", (chunk) => {
-                stderr += chunk.toString("utf8");
-            });
-            child.on("error", (err) => {
-                clearTimeout(timeoutHandle);
-                resolve(cb([], err.message));
-            });
-            child.on("close", (code) => {
-                clearTimeout(timeoutHandle);
-                if (timedOut) {
-                    resolve(cb([], `gh issue list timed out after ${timeoutMs}ms`));
-                    return;
-                }
-                if (code !== 0) {
-                    resolve(cb([], stderr.trim() || `gh issue list exited with code ${code}`));
-                    return;
-                }
-                resolve(cb(this.parseIssueList(stdout), null));
+            this.spawnList(state, repo, label, timeoutMs, (issues, err) => {
+                resolve(cb(issues, err));
             });
         });
     }
@@ -260,11 +167,10 @@ export class GitHubIssueDataSourceAdapter {
      * microtask gaps.
      */
     spawnList(state, repo, label, timeoutMs, cb) {
+        const child = this.createListProcess(state, repo, label);
         let stdout = "";
         let stderr = "";
         let timedOut = false;
-        const args = this.buildListArgs(state, repo, label);
-        const child = spawn(this.ghPath, args, { stdio: ["ignore", "pipe", "pipe"] });
         const timeoutHandle = setTimeout(() => {
             timedOut = true;
             child.kill("SIGTERM");
@@ -292,6 +198,80 @@ export class GitHubIssueDataSourceAdapter {
             cb(this.parseIssueList(stdout), null);
         });
     }
+    createListProcess(state, repo, label) {
+        const args = this.buildListArgs(state, repo, label);
+        return spawn(this.ghPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+    }
+    buildCountResult(sourceId, issues) {
+        return this.buildMetricResult(sourceId, issues.length, issues);
+    }
+    createSingleStateResultBuilder(sourceId) {
+        return (issues, err) => this.buildSingleStateResult(sourceId, issues, err);
+    }
+    createAggregateResultBuilder(sourceId, dimension) {
+        return (openIssues, closedIssues, err) => this.buildAggregateResult(sourceId, dimension, openIssues, closedIssues, err);
+    }
+    buildSingleStateResult(sourceId, issues, err) {
+        return err !== null ? this.buildErrorResult(sourceId, err) : this.buildCountResult(sourceId, issues);
+    }
+    buildAggregateResult(sourceId, dimension, openIssues, closedIssues, err) {
+        if (err !== null) {
+            return this.buildErrorResult(sourceId, err);
+        }
+        const aggregate = this.buildAggregateMetrics(openIssues, closedIssues);
+        const value = dimension === "total_issue_count" ? aggregate.totalCount : aggregate.completionRatio;
+        return {
+            ...this.buildMetricResult(sourceId, value, aggregate.allIssues),
+            metadata: this.buildCompletionMetadata(aggregate.openCount, aggregate.closedCount, aggregate.totalCount, aggregate.completionRatio),
+        };
+    }
+    buildErrorResult(sourceId, error) {
+        return {
+            value: null,
+            raw: [],
+            timestamp: new Date().toISOString(),
+            source_id: sourceId,
+            error,
+        };
+    }
+    buildMetricResult(sourceId, value, raw) {
+        return {
+            value,
+            raw,
+            timestamp: new Date().toISOString(),
+            source_id: sourceId,
+        };
+    }
+    buildUnknownDimensionResult(sourceId) {
+        return {
+            value: null,
+            raw: [],
+            timestamp: new Date().toISOString(),
+            source_id: sourceId,
+        };
+    }
+    buildCompletionMetadata(openCount, closedCount, totalCount, completionRatio) {
+        return {
+            open_count: openCount,
+            closed_count: closedCount,
+            total_count: totalCount,
+            completion_ratio: completionRatio,
+        };
+    }
+    buildAggregateMetrics(openIssues, closedIssues) {
+        const openCount = openIssues.length;
+        const closedCount = closedIssues.length;
+        const totalCount = openCount + closedCount;
+        const completionRatio = totalCount === 0 ? 0 : closedCount / totalCount;
+        const allIssues = [...openIssues, ...closedIssues];
+        return {
+            openCount,
+            closedCount,
+            totalCount,
+            completionRatio,
+            allIssues,
+        };
+    }
     buildListArgs(state, repo, label) {
         const args = [
             "issue",