@nightowlsdev/engine-ai-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Night Owls 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

@@ -0,0 +1,119 @@
+# @nightowlsdev/engine-ai-sdk
+
+> The AI-SDK-native engine, in the `engine-*` family — **v1 shipped**: a governed `ai@^6` `streamText` loop,
+> sibling to `@nightowlsdev/engine-mastra`'s Mastra-backed facade.
+
+Per the pluggable-engine architecture (`docs/strategy/2026-07-03-pluggable-engine-architecture.md` §2b), this
+package hosts a from-scratch swarm loop built directly on the Vercel AI SDK (`streamText`) rather than Mastra.
+It reuses the SAME governance plane as `engine-mastra` verbatim — `HookDispatcher`/`ToolApprovalPolicy`,
+`CostGovernor`/pricing, tier routing, secrets, telemetry — and passes both `verifyEngineContract` (the shared
+conformance suite) and a golden-trajectory parity gate against `engine-mastra`. v1 is **single-agent**: no
+delegation, no workflows, no semantic recall (see "What v1 doesn't do" below).
+
+## Install
+
+```sh
+pnpm add @nightowlsdev/engine-ai-sdk ai
+```
+
+## Usage
+
+```ts
+import { defineSwarm } from "@nightowlsdev/core";
+import { aiSdkEngine } from "@nightowlsdev/engine-ai-sdk";
+
+export default defineSwarm({
+  // ...
+  engine: aiSdkEngine(),
+});
+```
+
+## Capability matrix (vs. `engine-mastra`)
+
+| Capability | `engine-mastra` (default) | `engine-ai-sdk` (v1) |
+|---|---|---|
+| Delegation / multi-agent | ✅ agents-as-tools, depth+cycle guards, budgets | ❌ `delegation: false` (single-agent v1; `ask_slug` delegation planned v1.1) |
+| Workflows (strict/advisory) | ✅ `StepDriver` | ❌ `workflows: false` |
+| Semantic recall / working memory | ✅ Mastra Memory + pgvector | ❌ `memory.semanticRecall`/`workingMemory`/`observational: false` — `memory.history: true` only |
+| Tool approvals | ✅ SP5 waitpoint suspend | ✅ **native** `ai@6` per-tool `needsApproval` + engine-side `executeToolWithGate` fail-closed backstop |
+| HITL ask / client tools | ✅ | ✅ (same `ask`/client-action contract) |
+| Durable cross-process resume | ✅ (via Mastra store) | ◐ `hitl.durableResume` — **`false` by default**, opt-in via `aiSdkEngine({ durable: true })` (see below) |
+| Events | ✅ tier 3, 12/12 `SwarmEvent` types | ✅ tier 3, **11 of 12** — `swarm.handoff` absent (`delegation: false`) |
+| History source | Mastra Memory / message store | **Events-derived**: `history()`/reads are built from the persisted event log, not a separate message store |
+| Cost governance, secrets, telemetry, scratchpad, cancellation (mid-stream) | ✅ | ✅ (same code, reused verbatim from core) |
+| Rules (advise/enforce) | ✅ | ✅ |
+
+The static descriptor is exported as `AI_SDK_ENGINE_CAPABILITIES` (`docs/spec/ENGINE-CONTRACT.md` §2c shape).
+
+### Tier-3-without-handoff note
+
+`AI_SDK_ENGINE_CAPABILITIES.events.tier` is declared `3` (the metering tier), but `events.emits` deliberately
+**excludes `swarm.handoff`** — handoff is a delegation-only event, and this engine's `delegation` is `false`.
+**`emits` is authoritative over the declared tier** for which events actually stream: consumers (react's
+`useEngineCapabilities()`, the runner boot guards) should check `emits.includes(type)`, not infer event
+support purely from the tier number.
+
+### The `durable` flag
+
+```ts
+aiSdkEngine({ durable?: boolean })  // default: false
+```
+
+`durableResume` is a per-**instance** capability flip, never inferred from the injected `StorageAdapter` —
+mirroring `engine-mastra`'s own construction contract. Pass `aiSdkEngine({ durable: true })` **only** when
+your `StorageAdapter` persists suspend/resume snapshots **across processes** (e.g.
+`@nightowlsdev/storage-supabase`). Leave the default `false` for any storage that doesn't (in-memory / dev,
+or a `StorageAdapter` you haven't verified), so `@nightowlsdev/runner-background` and `@nightowlsdev/mcp-server`
+keep treating `ask`/approval resumes as **non-durable** and advise/warn accordingly instead of silently
+promising a resume that can't survive a process restart.
+
+## What v1 doesn't do (honesty list)
+
+- **No delegation** — `delegation: false`. Multi-agent packs (agent-kit's crews, Growth Strategist, Design
+  Studio) require `engine-mastra` until `ask_slug`-based delegation ships in **v1.1**.
+- **No workflows** — `workflows: false`. Strict/advisory `defineWorkflow` procedures are not (yet) ported;
+  use `engine-mastra` for workflow-driven swarms.
+- **No semantic recall** — `memory.semanticRecall`, `memory.workingMemory`, and `memory.observational` are
+  all `false`. Only `memory.history` (event-log-derived message history) is supported.
+- **`governance.preToolCall` cap-ask `'ask'` deferred** — the cap-hit `ask` escalation path is deferred; see
+  the engine source for the current cap-hit behavior.
+- **`ask`/client-resume emits no `swarm.tool_result`** — a documented wire asymmetry vs. `engine-mastra`: on
+  resume, the built-in `ask` tool is execute-less on this engine, so there is no tool-result to report for
+  the answered call (verified as a legitimate divergence by the cross-engine parity suite, not a bug).
+
+## API
+
+### `aiSdkEngine(opts?)`
+
+```ts
+function aiSdkEngine(opts?: { durable?: boolean }): (opts: AssembledEngineOpts) => Engine
+```
+
+Returns an engine factory for `defineSwarm({ engine })`. Constructs a governed `ai@^6` `streamText` loop
+(`AiSdkEngine`) from the fully-assembled `AssembledEngineOpts` `defineSwarm` hands it — the same construction
+contract `engine-mastra`'s `mastraEngine()` follows.
+
+### `AiSdkEngine`
+
+The concrete `Engine` implementation. Re-exported from the package barrel for direct construction/typing.
+
+### `AI_SDK_ENGINE_CAPABILITIES`
+
+The engine's static `EngineCapabilities` descriptor (`docs/spec/ENGINE-CONTRACT.md`). `id: "ai-sdk"`, tier-3
+events (`swarm.handoff` absent — see the note above), full HITL except durable resume by default, no
+delegation, no workflows, mid-stream cancellation, full governance (`preGeneration`, fail-closed
+`preToolCall`, cost caps, secrets), telemetry on.
+
+### `nightOwlsPlugin`
+
+The declarative plugin manifest consumed by `@nightowlsdev/cli` (`kind: "engine"`). Data-only — it does not
+import from `@nightowlsdev/cli` (no dependency cycle).
+
+## See also
+
+- [`docs/spec/ENGINE-CONTRACT.md`](../../docs/spec/ENGINE-CONTRACT.md) — the normative structural `Engine`
+  interface + behavioral invariants every engine (this one included) must satisfy.
+- [`docs/strategy/2026-07-03-pluggable-engine-architecture.md`](../../docs/strategy/2026-07-03-pluggable-engine-architecture.md)
+  §2b — the engine family, the value proposition for a second native engine, and the v1.1+ roadmap.
+- `@nightowlsdev/engine-mastra` — the sibling default (Mastra-backed) engine package; the multi-agent /
+  workflow / semantic-recall path today.