logicsrc/packages/agentstack/PRD.md

# AgentStack — Product Requirements Document

- **Package:** `@logicsrc/agentstack`
- **Status:** v0.1.0 — in-memory reference implementation
- **Spec of record:** `profullstack-web/openspec/specs/agentstack` (Profullstack Shared AppKit OpenSpec)
- **Owner:** Profullstack / LogicSRC

## 1. Summary

AgentStack is the LogicSRC module for **portable agent, task, payment, and reputation
coordination** across the Profullstack microsaas family (sh1pt, uGig, qaaas.dev, crawlproof,
commandboard.run, coinpayportal, logicsrc, intr0s). It gives every app a shared vocabulary for
"who is acting, on whose behalf, on what task, and how it gets paid and scored" — without a
single shared user database or shared cookies.

Identity is anchored on CoinPay-linked DIDs (`did:coinpay:user:123`, `did:coinpay:agent:abc`),
so each app keeps its local `users.id` and links it to a portable DID. Tasks are DID-addressable
and carry their own status lifecycle plus hooks for payment, escrow, and reputation events.

## 2. Problem & motivation

Profullstack apps increasingly hand work to autonomous agents and to each other (a gig posted in
uGig becomes a build task in commandboard.run, paid through CoinPay, scored in a shared
reputation ledger). Today each app reinvents:

- how an agent or user is identified across app boundaries,
- what a "task" is and which states it can move through,
- how a task binds to a payment intent, escrow hold, and reputation event,
- how one app delegates authority to an agent owned by another.

The result is bespoke, incompatible glue per integration. AgentStack standardizes the model once,
as a runtime-neutral module any app can embed or call.

## 3. Goals / non-goals

### Goals
- A single portable task and agent model shared by all Profullstack apps.
- CoinPay-DID identity that works **without** shared auth state.
- A defined, validated task status lifecycle with payment/escrow/reputation linkage points.
- Delegation grants that let an owner authorize an agent within explicit scopes.
- A coordination event stream apps can subscribe to.
- Ship as a LogicSRC plugin (`agentStackPlugin`) validated against the plugin manifest schema.
- Runtime-neutral: identical behavior on Bun, Node.js, Cloudflare Workers, and the browser.

### Non-goals (for now)
- AgentStack is **not** an auth provider — it consumes CoinPay DIDs, it does not mint them.
- It is **not** a payments processor — it references CoinPay payment/escrow IDs, it does not move money.
- It does **not** define the wire transport between apps in v0.1 (in-memory only); the API/server
  surface is a later milestone.
- It does **not** own agent execution/runtime — it coordinates, it does not run the agent.

## 4. Users & use cases

| Persona | Use case |
| --- | --- |
| App developer | Embed `AgentStack` to register agents and track tasks with a consistent model. |
| Owner (human user) | Delegate scoped authority to an agent to act across apps on their behalf. |
| Agent | Receive assigned tasks, report status transitions, accrue reputation. |
| Platform / ops | Subscribe to coordination events for audit, dashboards, and cross-app federation. |

Representative flows:
1. uGig publishes a paid gig → AgentStack task created with a `paymentIntentId` and `escrowId`.
2. commandboard.run's build agent is assigned the task and reports `running → complete`.
3. Completion references a `reputationEventId`; CoinPay releases escrow out of band.

## 5. Current state (v0.1.0 — implemented)

Backed by `src/index.ts`, `src/types.ts`, `src/manifest.ts`:

- **DID helpers** — `makeDid`, `userDid`, `agentDid`, `parseDid`, `DID_METHOD = "did:coinpay"`,
  and the `isDidTask` type guard.
- **`DidTask` model** — id, owner/assignee DIDs, `sourceApp`, title/description, `status`, and
  linkage fields `paymentIntentId` / `escrowId` / `reputationEventId`, plus `metadata` and timestamps.
- **Status lifecycle** — `pending → queued → running → blocked → complete | failed | cancelled`.
- **`AgentStack` coordinator** (in-memory `Map` storage, injectable clock):
  `registerAgent`, `getAgent`, `createTask`, `getTask`, `assignTask`, `updateTaskStatus`,
  `delegate`, `revokeDelegation`, `listTasks`, `snapshot`, and an `on(listener)` event subscription.
- **Events** — `agent.registered`, `task.created`, `task.assigned`, `task.updated`,
  `delegation.granted`, `delegation.revoked`.
- **`agentStackPlugin`** — a LogicSRC `PluginDefinition`, plus `agentStackManifest` declaring
  capabilities (`agents.register`, `agents.delegate`, `tasks.create/assign/update/publish`,
  `reputation.sync`, `payments.link`, `escrow.link`), commands (`agents`, `tasks`, `delegate`),
  and env (`AGENTSTACK_API_URL`, `AGENTSTACK_API_KEY`, `COINPAY_API_BASE_URL`).
- **Tests** — vitest suite in `src/index.test.ts`.

> Note: the payment/escrow/reputation fields and the `payments.link` / `escrow.link` /
> `reputation.sync` / `tasks.publish` capabilities are **declared and stored** today, but their
> live integrations and cross-app transport are not yet implemented (see roadmap).

## 6. Functional requirements

- **FR-1 Identity.** All actors are addressed by `did:coinpay:{user|agent}:{id}`. Invalid DIDs are
  rejected by `parseDid`. Apps map local `users.id ↔ DID`; AgentStack never stores credentials.
- **FR-2 Agents.** Register an `AgentProfile` (name, sourceApp, supported protocols, optional
  inbox/task endpoints, reputation score). Re-registration updates the profile.
- **FR-3 Tasks.** Create DID-addressable tasks bound to a `sourceApp`. Tasks may be assigned to an
  agent and carry optional payment/escrow IDs at creation.
- **FR-4 Lifecycle.** Status transitions follow the defined lifecycle; terminal states
  (`complete`, `failed`, `cancelled`) are final. `updatedAt` advances on every change.
- **FR-5 Delegation.** An owner grants an agent a scoped, optionally time-bounded
  `DelegationGrant`; grants can be revoked. Authority checks reference active grants.
- **FR-6 Events.** Every state-changing operation emits a typed `AgentStackEvent`; listeners can
  subscribe/unsubscribe.
- **FR-7 Linkage.** Tasks reference `paymentIntentId`, `escrowId`, and `reputationEventId` so
  external systems (CoinPay, reputation ledger) can correlate without coupling.
- **FR-8 Plugin.** AgentStack is exposed as a validated LogicSRC plugin with routes, events,
  permissions, and a TUI panel.

## 7. Non-functional requirements

- **Runtime-neutral:** pure TypeScript, no Bun/Node-only APIs; time injected via constructor.
  Must run on Bun, Node.js, Cloudflare Workers, and the browser (Profullstack dual-runtime standard).
- **Storage-agnostic:** the in-memory coordinator's API is the contract; persistent backends wrap
  the same surface.
- **Spec-conformant:** behavior tracks the `agentstack` OpenSpec capability; drift is a bug.
- **Deterministic & testable:** injectable clock and ID generation; covered by vitest.

## 8. Roadmap / milestones

- **M1 — In-memory core (done, v0.1.0).** DID helpers, task model + lifecycle, coordinator,
  delegation, events, plugin manifest, tests.
- **M2 — Persistence.** A storage backend interface + at least one durable adapter (SQLite/SQLite
  Cloud or Postgres) wrapping the coordinator API, with a snapshot/restore path.
- **M3 — API surface.** A client + server for `AGENTSTACK_API_URL` / `AGENTSTACK_API_KEY` so apps
  coordinate over the network, not just in-process; event stream over the wire.
- **M4 — Live integrations.** Wire `payments.link` / `escrow.link` to CoinPay (`COINPAY_API_BASE_URL`)
  and `reputation.sync` to the shared reputation ledger; enforce delegation scopes on operations.
- **M5 — Cross-app federation.** Implement `tasks.publish` so a task created in one app is
  discoverable/claimable in another; SDK contracts (Rust/Bun/Node/Python/curl) and MCP server hooks.
- **M6 — TUI & ops.** Flesh out the `agents` / `tasks` / `delegate` TUI commands and plugin status UI.

## 9. Success metrics

- ≥ 3 Profullstack apps embedding AgentStack with no per-integration task/identity glue.
- 100% of task state changes emitted as auditable events.
- Zero shared-auth dependencies — all cross-app identity flows through CoinPay DIDs.
- Reference suite green on all four target runtimes.

## 10. Open questions

- Delegation enforcement: should the coordinator hard-block out-of-scope operations, or surface a
  violation event for the host app to enforce?
- Persistence: standardize on one backend, or ship an adapter interface and let each app choose?
- Lifecycle: are `blocked → queued` re-entries allowed, or is `blocked` a one-way precursor to a
  terminal state?
- Federation trust: how are agent profiles and reputation scores verified across app boundaries?