@stackbone/sdk 0.1.0-alpha.6 → 0.1.0-alpha.8

package/CHANGELOG.md

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0-alpha.8] - 2026-07-01
+
+### Added
+
+- **`stackbone.workflows` — namespaced workflow trigger + schedule surface on the
+  ambient client.** `stackbone.workflows.start(name, input)` (fire-and-forget),
+  `.startAndWait<T>(name, input)` (durable sub-routine), `.schedule(name, input,
+cron)` / `.unschedule(name)` / `.listSchedules()` (dynamic cron). These are the
+  peer-free shims over the runtime-injected `WorkflowStarter` / `WorkflowScheduler`
+  seams, now exposed under one unified `stackbone.*` namespace alongside
+  `stackbone.connection` / `stackbone.agent`. The main barrel stays peer-free.
+
+### Deprecated
+
+- The loose `startWorkflow` / `startWorkflowAndWait` / `scheduleWorkflow` /
+  `unschedule` / `listSchedules` exports on the `@stackbone/sdk/workflow` subpath
+  are now `@deprecated` aliases that delegate to the identical implementation —
+  prefer the namespaced `stackbone.workflows.*` members. The peer-bound authoring
+  API (`requestApproval` / `defineHook` / `sleep`) stays on the subpath because it
+  eager-loads the `workflow` peer.
+
+## [0.1.0-alpha.7] - 2026-06-25
+
+### Added
+
+- **Workflow-level Human-in-the-Loop (HITL) on the new `@stackbone/sdk/workflow`
+  subpath.** `requestApproval({ token, topic, payload, title, timeout, fallback })`
+  pauses a durable workflow on a Workflow SDK hook, records the pause in the
+  agent's `approvals` table (joined to the run so it shows in the inbox), and
+  races the human decision against the `timeout` — applying the `fallback`
+  (`'reject' | 'approve'`) if nobody decides. The caller gates the side-effect on
+  `decision.status === 'approved'`. The raw `defineHook` + `sleep` primitives are
+  re-exported from the same subpath as the escape hatch. Neither may run inside a
+  `"use step"` block (`.create()` is a workflow primitive that suspends the run).
+  The subpath statically imports the new OPTIONAL `workflow` peer dependency
+  (kept external by the build), so the main `@stackbone/sdk` barrel stays free of
+  it — a tool-only agent never eager-loads `workflow`.
+- **`ApprovalRequestOptions.runId`** — `client.approval.request(...)` now accepts
+  a `runId` that is written to `approvals.run_id` (FK to `runs.id`), so an
+  approval can be tied to the projected run that requested it.
+- **`eveAgent(name)` on the `@stackbone/sdk/workflow` subpath.** Addresses a
+  sibling eve agent BY NAME from a workflow `"use step"` and returns eve's `Client`
+  as-is (a thin wrapper — drive it with eve's own `.session()` / `.send()` API).
+  The name resolves to a URL through the emulator-injected `AGENT_URLS` map; each
+  request is signed with the shared `HMAC_SECRET` (timestamp-bound bearer under
+  `x-stackbone-timestamp` / `x-stackbone-workflow-signature`, verified inside a
+  5-minute drift window) so the agent's channel auth accepts the co-located hop.
+  The helper statically imports the new OPTIONAL `eve` peer dependency (kept
+  external by the build), so the main `@stackbone/sdk` barrel stays free of it.
+- **`stackbone.agent(id)` — the namespaced sibling-agent member on the ambient
+  client.** `stackbone.agent('support').session().send({ ... })` produces the same
+  signed workflow→agent call and the same eve `Client` API as the now-`@deprecated`
+  top-level `eveAgent('support')` on the `/workflow` subpath, narrowed by the same
+  augmentable `AgentRegistry` (declared names autocomplete, a typo is a compile
+  error). The crux is peer isolation: unlike `eveAgent`, the member imports NO `eve`
+  peer at module load — selecting the agent and opening a session are synchronous,
+  and only the session's already-async leaves (`send` / `stream`) resolve
+  `eve/client` via dynamic import on first use, then memoise it so conversation
+  state carries across turns. A tool-only agent that imports `@stackbone/sdk` and
+  only touches `stackbone.config` never loads `eve`. Verified by a no-peer import
+  regression test (the main barrel `index.js` statically imports neither `eve` nor
+  `workflow`).
+- **`stackbone.agent(id).session()` is now a DROP-IN twin of eve's native
+  `ClientSession`.** A workflow written against the eager `eveAgent(...)` path keeps
+  compiling verbatim when it swaps to `stackbone.agent(...)`: `session.send<T>(...)`
+  returns eve's `MessageResponse<T>` (so both `.result()` — typed `.data` — and
+  `for await...of` work), `session.session(state)` accepts eve's nominal
+  `SessionState` (`{ continuationToken?, sessionId?, streamIndex }`), and
+  `session.state` exposes the advanced cursor to persist between turns. These
+  peer-free structural mirrors are exported from the main barrel as
+  `EveMessageResponse` / `EveMessageResult` / `EveSessionState` / `EveStreamEvent` /
+  `SendTurnInput` (plus `AgentAccessor` / `LazyAgentClient` / `LazyAgentSession` /
+  `AgentRegistry`) so a workflow can name the handle, the response, the cursor and
+  the forwarded stream frame without reaching for the optional `eve` peer.
+  Previously the lazy session typed `send` as `Promise<unknown>` and omitted
+  `state`, so those usages did not type-check — only the eager path did.
+
+### Deprecated
+
+- **`eveAgent(name)`** (on the `@stackbone/sdk/workflow` subpath) in favour of the
+  namespaced `stackbone.agent(id)` from the main barrel. The old export still works
+  and is byte-identical on the wire; it just resolves the `eve` peer eagerly (the
+  subpath already imports it) instead of lazily.
+
+### Documentation
+
+- **Public docs + starter templates moved to the namespaced reach-by-id surface.**
+  The developer wiki gains a dedicated `stackbone.agent` page, documents
+  `stackbone.connection(id)` alongside the workspace-broker `client.legacyConnections`,
+  and shows the ambient `stackbone` handle with both reach-by-id members in the SDK
+  overview — each with a note that the top-level `eveAgent(...)` / bare
+  `connection(...)` forms are deprecated aliases. The starter's `AGENTS.md` now
+  models `stackbone.agent(...)` / `stackbone.connection(...)` for agent-to-agent and
+  connector calls. The CLI's inline `stackbone docs` bundle is regenerated from the
+  wiki so the new surface ships with the next CLI release.
+
 ## [0.1.0-alpha.6] - 2026-06-17
 
 ### Added