@nanobpm/agentic 0.1.0

package/README.md

@@ -0,0 +1,22 @@
+# @nanobpm/agentic
+
+The **Nano agentic protocol** (ADR 0056): one app-tier channel carrying agent presence/registry, demand×supply, a shared blackboard and a live terminal relay. One published package, subpath exports per family.
+
+## Subpath exports
+
+| Import | What |
+| --- | --- |
+| `@nanobpm/agentic/protocol` | Wire contract, frame codec, routing-token grammar, vocab schema (S0) |
+| `@nanobpm/agentic/protocol/conformance` | Shared conformance corpus |
+| `@nanobpm/agentic/channel` | App-tier channel & hub, connection registry, auth (S1) |
+| `@nanobpm/agentic/presence` | Presence & registry family (S2) |
+| `@nanobpm/agentic/vocab` | Vocab resolver + core vocabulary (S3) |
+| `@nanobpm/agentic/demand` | Demand×supply model (S4) |
+| `@nanobpm/agentic/relay` | Relay ring + QoS scheduler (S5) |
+| `@nanobpm/agentic/transcript` | Transcript store, retention-by-lifecycle (S6) |
+| `@nanobpm/agentic/blackboard` | Blackboard channel family (S7) |
+| `@nanobpm/agentic/cockpit` | Operator visibility page — the cockpit (S8) |
+
+The barrel `@nanobpm/agentic` re-exports each family as a namespace (`protocol`, `channel`, …). The worker-side client ships separately as `@nanobpm/urban-agent-client`.
+
+The wire contract is the single source of truth; nothing here rides the Camunda-8 engine or its transport.

package/dist/blackboard/family.d.ts

@@ -0,0 +1,40 @@
+import type { AgenticHub, HubConnection } from "../channel/index.ts";
+import type { BlackboardStore } from "./store.ts";
+export interface BlackboardFamilyOptions {
+    /**
+     * Resolve the board `scope` for a connection. Default: the capability
+     * credential presented at the handshake (`handshake.credential` or the
+     * `?capability=` query param) — so each distinct capability is its own board,
+     * exactly as nano-workforce's per-plan token is. Return `undefined` to reject
+     * the frame (the connection is not scoped to any board).
+     */
+    scopeOf?: (ctx: HubConnection) => string | undefined;
+    /**
+     * Notified of a fault this module handles while keeping the connection: a
+     * malformed blackboard payload ({@link BlackboardPayloadError}), a missing
+     * board scope, or a store error. Other exceptions propagate to {@link AgenticHub}.
+     */
+    onError?: (err: unknown, connectionId?: string) => void;
+}
+/** Handle to the attached blackboard family. */
+export interface BlackboardFamilyHandle {
+    /** Detach is a no-op today; present for symmetry with the other family modules. */
+    stop(): void;
+}
+/** A malformed blackboard payload rejected before it touches the store. */
+export declare class BlackboardPayloadError extends Error {
+    constructor(detail: string);
+}
+/** Raised when a connection is not scoped to any board (no capability scope). */
+export declare class BlackboardScopeError extends Error {
+    constructor();
+}
+/**
+ * Attach the blackboard family (`blackboard`) to `hub`, backed by `store`.
+ * Registers one handler via the S1 seam. Returns a handle for symmetry with the
+ * other family modules.
+ *
+ * @throws DuplicateFamilyHandlerError if the `blackboard` family already has a
+ *   handler on this hub (one family, one owning module).
+ */
+export declare function attachBlackboardFamily(hub: AgenticHub, store: BlackboardStore, options?: BlackboardFamilyOptions): BlackboardFamilyHandle;

package/dist/blackboard/family.js

@@ -0,0 +1,151 @@
+/**
+ * The blackboard family module — S7's self-contained attachment to the S1 hub.
+ *
+ * This module owns the `blackboard` message family. It attaches through the hub's
+ * canonical {@link AgenticHub.registerFamilyHandler} seam — it does NOT touch a
+ * shared frame→family dispatch switch — so it composes with the other family
+ * modules (S2 presence, S5 relay) with no shared edit.
+ *
+ * It promotes nano-workforce's per-plan blackboard HTTP hook to a first-class,
+ * capability-scoped channel family. Two operations ride the one `blackboard`
+ * family, distinguished by `payload.op`:
+ *
+ *  - `append` — idempotently write an entry (kinds `file-claim`,
+ *    `constraint-change`, `scope-change`, `learning`, `note`). The reply carries
+ *    `{ inserted, id, conflicts }`; for a `file-claim`, `conflicts` lists prior
+ *    claims by OTHER authors on the same files (first-writer-wins, advisory).
+ *  - `read` — return the board's entries after `since` plus the head `cursor`
+ *    for incremental polling.
+ *
+ * The board `scope` is CAPABILITY-DERIVED: by default it is the connection's
+ * capability credential (the same credential the S1 handshake gated on — the
+ * per-board token nano-workforce's hook already uses as the credential). A
+ * connection can therefore only read/write the board its capability authorises,
+ * with no board id trusted from the payload. Override {@link BlackboardFamilyOptions.scopeOf}
+ * to derive the scope differently (e.g. from an ADR 0028 grant scope).
+ *
+ * Replies ride the control/facts lane so a blackboard write is never
+ * head-of-line-blocked behind a bulk-output storm (invariant 5).
+ */
+import { validatePayload } from "../protocol/index.js";
+/** A malformed blackboard payload rejected before it touches the store. */
+export class BlackboardPayloadError extends Error {
+    constructor(detail) {
+        super(`invalid blackboard payload: ${detail}`);
+        this.name = "BlackboardPayloadError";
+    }
+}
+/** Raised when a connection is not scoped to any board (no capability scope). */
+export class BlackboardScopeError extends Error {
+    constructor() {
+        super("connection is not scoped to any blackboard");
+        this.name = "BlackboardScopeError";
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}
+function readStringArray(record, key) {
+    const value = record[key];
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((v) => typeof v === "string");
+}
+/** The default scope resolver: the connection's capability credential. */
+function defaultScopeOf(ctx) {
+    const credential = ctx.handshake.credential ?? ctx.handshake.query?.capability;
+    const scope = credential?.trim();
+    return scope !== undefined && scope !== "" ? scope : undefined;
+}
+/**
+ * Attach the blackboard family (`blackboard`) to `hub`, backed by `store`.
+ * Registers one handler via the S1 seam. Returns a handle for symmetry with the
+ * other family modules.
+ *
+ * @throws DuplicateFamilyHandlerError if the `blackboard` family already has a
+ *   handler on this hub (one family, one owning module).
+ */
+export function attachBlackboardFamily(hub, store, options = {}) {
+    store.ensureSchema();
+    const onError = options.onError ?? (() => { });
+    const scopeOf = options.scopeOf ?? defaultScopeOf;
+    const reject = (connectionId, detail) => {
+        onError(new BlackboardPayloadError(detail), connectionId);
+    };
+    hub.registerFamilyHandler("blackboard", (frame, ctx) => {
+        const payload = frame.payload;
+        const result = validatePayload("blackboard", payload);
+        if (!result.ok) {
+            reject(ctx.id, result.errors.map((e) => e.message).join("; "));
+            return;
+        }
+        if (!isPlainObject(payload)) {
+            reject(ctx.id, "not an object");
+            return;
+        }
+        const scope = scopeOf(ctx);
+        if (scope === undefined) {
+            onError(new BlackboardScopeError(), ctx.id);
+            return;
+        }
+        const op = payload.op;
+        try {
+            if (op === "read") {
+                handleRead(store, ctx, frame, scope, payload);
+                return;
+            }
+            // validatePayload already constrained op ∈ {append, read}.
+            handleAppend(store, ctx, frame, scope, payload, reject);
+        }
+        catch (err) {
+            onError(err, ctx.id);
+        }
+    });
+    return {
+        stop() { },
+    };
+}
+function handleRead(store, ctx, frame, scope, payload) {
+    const rawSince = payload.since;
+    const since = typeof rawSince === "number" ? rawSince : undefined;
+    const page = store.readPage(scope, { since });
+    // `scope` is NOT echoed: under the default resolver it is the connection's
+    // capability credential (a secret), and it is server-derived so the client
+    // never needs it back for routing. Echoing it would only widen its exposure
+    // to logs/recordings.
+    ctx.send(reply(frame, { op: "read", cursor: page.cursor, entries: page.entries }));
+}
+function handleAppend(store, ctx, frame, scope, payload, reject) {
+    const body = readString(payload, "body");
+    if (body === undefined || body.trim() === "") {
+        reject(ctx.id, "append requires a non-empty body");
+        return;
+    }
+    const files = readStringArray(payload, "files");
+    const wave = typeof payload.wave === "number" ? payload.wave : undefined;
+    const input = {
+        authorTask: readString(payload, "authorTask"),
+        kind: payload.kind,
+        files,
+        body,
+        wave,
+        dedupeKey: readString(payload, "dedupeKey"),
+    };
+    const { inserted, id } = store.append(scope, input);
+    // Conflict-of-intent is reported only for a file-claim carrying files: prior
+    // claims by OTHER authors on the same files, decided by insertion order
+    // (beforeId = this row's id), exactly as the HTTP hook did.
+    let conflicts = [];
+    if (input.kind === "file-claim" && files && files.length > 0) {
+        conflicts = store.detectFileClaimConflicts(scope, { authorTask: input.authorTask, files, beforeId: id });
+    }
+    ctx.send(reply(frame, { op: "append", inserted, id, conflicts }));
+}
+/** Build a control-lane blackboard reply that echoes the request `seq` for correlation. */
+function reply(request, payload) {
+    return { lane: "control", family: "blackboard", seq: request.seq, payload };
+}

package/dist/blackboard/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @nanobpm/agentic-blackboard — the blackboard family for the Nano agentic
+ * protocol (ADR 0056, slice S7).
+ *
+ * Promotes nano-workforce's per-plan blackboard HTTP hook to a first-class,
+ * capability-scoped `blackboard` channel-message family: a durable per-scope
+ * coordination store ({@link BlackboardStore}) with idempotent `dedupeKey`
+ * append, `file-claim` conflict reporting and `since`/cursor incremental reads,
+ * plus a self-contained family module ({@link attachBlackboardFamily}) that
+ * attaches to the S1 hub through its `registerFamilyHandler(family, handler)`
+ * seam — never a shared dispatch switch. Any Urban app gets the blackboard for
+ * free by attaching this module.
+ *
+ * The wire contract lives in `@nanobpm/agentic-protocol`; the hub in
+ * `@nanobpm/agentic-channel`. This package builds on both.
+ */
+export { BlackboardStore, isUniqueViolation, normalizeKind, systemClock, BLACKBOARD_KINDS, } from "./store.ts";
+export type { BlackboardEntry, BlackboardInput, BlackboardKind, BlackboardPage, BlackboardStoreOptions, ClaimConflict, Clock, SqliteDb, } from "./store.ts";
+export { attachBlackboardFamily, BlackboardPayloadError, BlackboardScopeError, } from "./family.ts";
+export type { BlackboardFamilyOptions, BlackboardFamilyHandle } from "./family.ts";
+export { BLACKBOARD_TABLE, BLACKBOARD_SCHEMA_SQL } from "./schema.ts";

package/dist/blackboard/index.js

@@ -0,0 +1,19 @@
+/**
+ * @nanobpm/agentic-blackboard — the blackboard family for the Nano agentic
+ * protocol (ADR 0056, slice S7).
+ *
+ * Promotes nano-workforce's per-plan blackboard HTTP hook to a first-class,
+ * capability-scoped `blackboard` channel-message family: a durable per-scope
+ * coordination store ({@link BlackboardStore}) with idempotent `dedupeKey`
+ * append, `file-claim` conflict reporting and `since`/cursor incremental reads,
+ * plus a self-contained family module ({@link attachBlackboardFamily}) that
+ * attaches to the S1 hub through its `registerFamilyHandler(family, handler)`
+ * seam — never a shared dispatch switch. Any Urban app gets the blackboard for
+ * free by attaching this module.
+ *
+ * The wire contract lives in `@nanobpm/agentic-protocol`; the hub in
+ * `@nanobpm/agentic-channel`. This package builds on both.
+ */
+export { BlackboardStore, isUniqueViolation, normalizeKind, systemClock, BLACKBOARD_KINDS, } from "./store.js";
+export { attachBlackboardFamily, BlackboardPayloadError, BlackboardScopeError, } from "./family.js";
+export { BLACKBOARD_TABLE, BLACKBOARD_SCHEMA_SQL } from "./schema.js";

package/dist/blackboard/schema.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The canonical blackboard schema.
+ *
+ * The DDL here is the single source of truth the {@link BlackboardStore} applies
+ * through {@link BlackboardStore.ensureSchema}. The very same statements are
+ * mirrored in the app-boot migration `db/migrations/003_agentic_blackboard.sql`
+ * (applied by the DataLayer migration runner). To keep those two application
+ * paths from drifting, `schema.test.ts` normalises both and asserts they are
+ * statement-for-statement identical — divergence is a red test, not a silent
+ * production/boot mismatch.
+ *
+ * The table promotes nano-workforce's per-plan `plan_blackboard` HTTP hook to a
+ * first-class channel-family store: the same idempotent-append (`dedupe_key`),
+ * conflict-of-intent (`file-claim`) and incremental-read (`id`/cursor) semantics,
+ * generalised from a hard-wired `plan_key` to a capability-derived `scope` so any
+ * Urban app gets it for free.
+ */
+/** The blackboard table name. */
+export declare const BLACKBOARD_TABLE = "agentic_blackboard";
+/**
+ * The canonical blackboard DDL. Forward-only and additive; every column added
+ * here must also be added to the boot migration (the drift guard enforces it).
+ *
+ * Idempotency: the partial UNIQUE index over `(scope, dedupe_key)` (NULLs
+ * excluded, so a dedupe-less note always appends) collapses a re-POST carrying a
+ * stable `dedupe_key` to one row — the engine may re-activate a job on retry, so
+ * a repeated append must be a no-op. `(scope, id)` lists a board's entries in
+ * write order and drives the `since`/cursor incremental read.
+ */
+export declare const BLACKBOARD_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS agentic_blackboard (\n  id          INTEGER PRIMARY KEY AUTOINCREMENT,\n  scope       TEXT NOT NULL,\n  author_task TEXT NOT NULL DEFAULT 'system',\n  kind        TEXT NOT NULL DEFAULT 'note',\n  files       TEXT,\n  body        TEXT NOT NULL,\n  wave        INTEGER,\n  dedupe_key  TEXT,\n  created_at  TEXT NOT NULL\n);\nCREATE UNIQUE INDEX IF NOT EXISTS ux_agentic_blackboard_dedupe ON agentic_blackboard (scope, dedupe_key) WHERE dedupe_key IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_agentic_blackboard_scope ON agentic_blackboard (scope, id);";

package/dist/blackboard/schema.js

@@ -0,0 +1,42 @@
+/**
+ * The canonical blackboard schema.
+ *
+ * The DDL here is the single source of truth the {@link BlackboardStore} applies
+ * through {@link BlackboardStore.ensureSchema}. The very same statements are
+ * mirrored in the app-boot migration `db/migrations/003_agentic_blackboard.sql`
+ * (applied by the DataLayer migration runner). To keep those two application
+ * paths from drifting, `schema.test.ts` normalises both and asserts they are
+ * statement-for-statement identical — divergence is a red test, not a silent
+ * production/boot mismatch.
+ *
+ * The table promotes nano-workforce's per-plan `plan_blackboard` HTTP hook to a
+ * first-class channel-family store: the same idempotent-append (`dedupe_key`),
+ * conflict-of-intent (`file-claim`) and incremental-read (`id`/cursor) semantics,
+ * generalised from a hard-wired `plan_key` to a capability-derived `scope` so any
+ * Urban app gets it for free.
+ */
+/** The blackboard table name. */
+export const BLACKBOARD_TABLE = "agentic_blackboard";
+/**
+ * The canonical blackboard DDL. Forward-only and additive; every column added
+ * here must also be added to the boot migration (the drift guard enforces it).
+ *
+ * Idempotency: the partial UNIQUE index over `(scope, dedupe_key)` (NULLs
+ * excluded, so a dedupe-less note always appends) collapses a re-POST carrying a
+ * stable `dedupe_key` to one row — the engine may re-activate a job on retry, so
+ * a repeated append must be a no-op. `(scope, id)` lists a board's entries in
+ * write order and drives the `since`/cursor incremental read.
+ */
+export const BLACKBOARD_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${BLACKBOARD_TABLE} (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  scope       TEXT NOT NULL,
+  author_task TEXT NOT NULL DEFAULT 'system',
+  kind        TEXT NOT NULL DEFAULT 'note',
+  files       TEXT,
+  body        TEXT NOT NULL,
+  wave        INTEGER,
+  dedupe_key  TEXT,
+  created_at  TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS ux_${BLACKBOARD_TABLE}_dedupe ON ${BLACKBOARD_TABLE} (scope, dedupe_key) WHERE dedupe_key IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_${BLACKBOARD_TABLE}_scope ON ${BLACKBOARD_TABLE} (scope, id);`;

package/dist/blackboard/store.d.ts

@@ -0,0 +1,138 @@
+/**
+ * The minimal synchronous SQLite handle the store needs — structurally the same
+ * surface the Urban runtime's DataLayer exposes (`host.openSqlite`). Kept local
+ * so the store depends on a shape, not on the runtime package.
+ */
+export interface SqliteDb {
+    /** Execute one or more statements with no result (DDL, migrations). */
+    exec(sql: string): void;
+    /** Run a parameterised statement, returning the changed-row count. */
+    run(sql: string, params?: unknown[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /** Run a parameterised query, returning all rows as plain objects. */
+    all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+}
+/** A monotonic wall clock, injectable for deterministic tests. */
+export interface Clock {
+    now(): number;
+}
+/** The default clock: `Date.now()`. */
+export declare const systemClock: Clock;
+/** The recognised blackboard entry kinds (verbatim from nano-workforce). */
+export declare const BLACKBOARD_KINDS: readonly ["file-claim", "constraint-change", "scope-change", "learning", "note"];
+export type BlackboardKind = (typeof BLACKBOARD_KINDS)[number];
+/** Coerce an arbitrary `kind` to a known value, defaulting to "note". */
+export declare function normalizeKind(kind: unknown): BlackboardKind;
+/** What a writer supplies to {@link BlackboardStore.append}. */
+export interface BlackboardInput {
+    /** The writing task's slug (or "system" for host writes). */
+    readonly authorTask?: string;
+    /** The entry kind; unrecognised values normalise to "note". */
+    readonly kind?: unknown;
+    /** Repo-relative paths this entry concerns (feeds `file-claim` conflicts). */
+    readonly files?: readonly string[];
+    /** The human/agent-readable note. Required and non-blank. */
+    readonly body: string;
+    /** Optional wave index the writer was dispatched in. */
+    readonly wave?: number | null;
+    /** Idempotency key; a repeat append under the same `scope` is a no-op. */
+    readonly dedupeKey?: string;
+}
+/** The parsed, agent-facing view of an entry (files decoded to an array). */
+export interface BlackboardEntry {
+    readonly id: number;
+    readonly authorTask: string;
+    readonly kind: string;
+    readonly files: string[];
+    readonly body: string;
+    readonly wave: number | null;
+    readonly createdAt: string;
+}
+/**
+ * An advisory conflict-of-intent: a sibling has already claimed a file this
+ * writer is about to claim. Reported per (file, prior claim) so the later
+ * claimer can back off, coordinate, or escalate. First-writer-wins is advisory
+ * only — the blackboard NEVER locks; merge-time gates are the real safety net.
+ */
+export interface ClaimConflict {
+    readonly file: string;
+    readonly authorTask: string;
+    readonly id: number;
+    readonly body: string;
+    readonly createdAt: string;
+}
+/** One incremental read: entries after `since` (write order) plus the `cursor`. */
+export interface BlackboardPage {
+    readonly entries: BlackboardEntry[];
+    /**
+     * The board's current head id — the true head even when `since` filters every
+     * entry out, so a caller that is fully caught up learns it is caught up
+     * (cursor unchanged). `0` for an empty board.
+     */
+    readonly cursor: number;
+}
+export interface BlackboardStoreOptions {
+    /** Injectable clock for deterministic `created_at` in tests. Default {@link systemClock}. */
+    readonly clock?: Clock;
+}
+/**
+ * True only for a UNIQUE / PRIMARY-KEY / duplicate violation — never a
+ * foreign-key or other constraint failure. We match the *specific* violation
+ * (extended SQLite codes, or the specific words) rather than the bare word
+ * "constraint", so a `FOREIGN KEY constraint failed` (real corruption, not a
+ * benign duplicate) is always rethrown rather than silently swallowed.
+ */
+export declare function isUniqueViolation(err: unknown): boolean;
+export declare class BlackboardStore {
+    #private;
+    constructor(db: SqliteDb, options?: BlackboardStoreOptions);
+    /**
+     * Apply the canonical blackboard DDL (idempotent). Callers that let the app
+     * DataLayer migration runner apply `db/migrations/003_agentic_blackboard.sql`
+     * do not need this — the family module calls it so the store is usable against
+     * a bare source too. The DDL is identical to the migration (drift-guarded).
+     */
+    ensureSchema(): void;
+    /**
+     * Append an entry to a board, idempotently. A blank `body` is rejected. When a
+     * `dedupeKey` is supplied and an entry already exists for it under this
+     * `scope`, the write is a no-op and the existing id is returned
+     * (`inserted: false`) — so an engine job retry re-appending the same fact
+     * never duplicates.
+     */
+    append(scope: string, input: BlackboardInput): {
+        inserted: boolean;
+        id: number;
+    };
+    /**
+     * One incremental read of a board: entries with `id > since` in write order,
+     * plus the board's current head `cursor`. An agent polling mid-flight passes
+     * `cursor` back as the next `since`, so it pulls only what siblings added since
+     * its last read.
+     */
+    readPage(scope: string, opts?: {
+        since?: number;
+    }): BlackboardPage;
+    /** A board's entries in write order (id asc). `since` returns only `id > since`. */
+    read(scope: string, opts?: {
+        since?: number;
+    }): BlackboardEntry[];
+    /**
+     * Prior `file-claim` entries by OTHER authors under this `scope` that overlap
+     * `files`. A writer's own earlier claim is never a conflict with itself. Pass
+     * `beforeId` to restrict to strictly prior claims (`id < beforeId`) — the
+     * family computes conflicts AFTER inserting its own claim and sets `beforeId`
+     * to that new id, so first-writer-wins is decided by insertion order and a
+     * sibling claim that raced in concurrently is still surfaced without matching
+     * the writer's own just-written row.
+     */
+    detectFileClaimConflicts(scope: string, opts: {
+        authorTask?: string;
+        files: readonly string[];
+        beforeId?: number;
+    }): ClaimConflict[];
+    /** Number of entries under a scope. */
+    count(scope: string): number;
+}