@labacacia/nps-sdk 1.0.0-alpha.1

package/src/nop/nop-types.ts

@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NOP Task Protocol — TypeScript Type Definitions
+// NPS-5 Neural Orchestration Protocol, MVP subset
+//
+// NCP carries the envelope. NOP fills the payload.
+// IntentFrame dispatches. ResultFrame reports back.
+
+// -----------------------------------------------------------------------------
+// NCP Envelope Types (NPS-1)
+// -----------------------------------------------------------------------------
+
+/** NCP protocol version marker */
+type NcpVersion = 1;
+
+/** Alternative approach considered but not taken */
+export interface Alternative {
+  value: string;
+  probability: number;
+}
+
+// -----------------------------------------------------------------------------
+// NOP Payload Types — Intent (Dispatch)
+// -----------------------------------------------------------------------------
+
+/** NOP protocol version marker */
+type NopVersion = 1;
+
+/** Task priority levels */
+export type Priority = "urgent" | "normal" | "low";
+
+/** Task category — what kind of work this is */
+export type TaskCategory = "code" | "research" | "docs" | "test" | "refactor" | "ops";
+
+/** Task mailbox paths — where files live during lifecycle */
+export interface Mailbox {
+  /** Base path for the task mailbox */
+  base: string;
+  /** Active directory name. Default: "active" */
+  active?: string;
+  /** Done directory name. Default: "done" */
+  done?: string;
+}
+
+/** Context the worker needs to do its job */
+export interface TaskContext {
+  /** File paths relevant to the task */
+  files?: string[];
+  /** Key facts the worker needs to know */
+  knowledge?: string[];
+  /** Git branch to work on */
+  branch?: string;
+}
+
+/** Boundaries the worker must operate within */
+export interface TaskConstraints {
+  /** Model to use: "sonnet", "haiku", "opus" */
+  model?: string;
+  /** Max seconds for task execution */
+  time_limit?: number;
+  /** Directories/files the worker may touch */
+  scope?: string[];
+  /** Whether changes need operator approval gate */
+  proceed_gate?: boolean;
+}
+
+/** NOP payload for task dispatch (MVP subset of TaskFrame 0x40) */
+export interface NopIntentPayload {
+  _nop: NopVersion;
+  /** Unique task ID: task-{source}-{YYYYMMDD}-{HHMMSS} */
+  id: string;
+  /** Who dispatched — NPS NID format: urn:nps:agent:{domain}:{name} */
+  from: string;
+  /** Target worker NID. Omit = any available worker picks up */
+  to?: string;
+  /** ISO 8601 timestamp when task was dispatched */
+  created_at: string;
+  /** Task priority. Default: "normal" */
+  priority?: Priority;
+  /** What kind of work this task involves */
+  category?: TaskCategory;
+  /** Where task files live during lifecycle */
+  mailbox: Mailbox;
+  /** Context for the worker */
+  context?: TaskContext;
+  /** Execution boundaries (NPS-5 §3.2 scope carving) */
+  constraints?: TaskConstraints;
+}
+
+// -----------------------------------------------------------------------------
+// NOP Payload Types — Result (Report Back)
+// -----------------------------------------------------------------------------
+
+/** Terminal task states (NPS-5 §4 state machine) */
+export type TaskStatus = "completed" | "failed" | "timeout" | "blocked";
+
+/** NOP payload for task result (AlignStream equivalent — NPS-5 §3.4) */
+export interface NopResultPayload {
+  _nop: NopVersion;
+  /** Same task ID from the intent */
+  id: string;
+  /** Terminal state */
+  status: TaskStatus;
+  /** Which worker executed — NPS NID format */
+  from: string;
+  /** ISO 8601 timestamp when worker claimed the task */
+  picked_up_at: string;
+  /** ISO 8601 timestamp when worker finished */
+  completed_at: string;
+  /** Files that were modified */
+  files_changed?: string[];
+  /** Git commit hashes + messages */
+  commits?: string[];
+  /** New tasks discovered during execution */
+  follow_up?: string[];
+  /** Seconds the task took */
+  duration?: number;
+  /** Error message if failed/timeout */
+  error?: string | null;
+}
+
+// -----------------------------------------------------------------------------
+// Full NCP+NOP Messages
+// -----------------------------------------------------------------------------
+
+/** Complete intent message: NCP envelope + NOP payload */
+export interface IntentMessage {
+  _ncp: NcpVersion;
+  type: "intent";
+  /** Short verb phrase: "fix-bug", "write-test", "research", "refactor" */
+  intent: string;
+  /** Orchestrator's confidence this is the right task/worker. 0-1 */
+  confidence: number;
+  /** NOP task payload */
+  payload: NopIntentPayload;
+}
+
+/** Complete result message: NCP envelope + NOP payload */
+export interface ResultMessage {
+  _ncp: NcpVersion;
+  type: "result";
+  /** Human-readable summary of what was done */
+  value: string;
+  /** Worker's confidence in the result quality. 0-1 */
+  probability: number;
+  /** Other approaches considered but not taken */
+  alternatives: Alternative[];
+  /** NOP result payload */
+  payload: NopResultPayload;
+}
+
+/** Any NOP message */
+export type NopMessage = IntentMessage | ResultMessage;
+
+// -----------------------------------------------------------------------------
+// Task Lifecycle (NPS-5 §4)
+// -----------------------------------------------------------------------------
+
+/** All possible task states */
+export type TaskState =
+  | "pending"    // inbox/ — waiting for pickup
+  | "active"     // active/ — worker executing
+  | "completed"  // done/ — success
+  | "failed"     // done/ — error
+  | "timeout"    // done/ — exceeded time_limit
+  | "blocked"    // blocked/ — needs external input
+  | "cancelled"; // done/ — orchestrator cancelled
+
+/** Valid state transitions */
+export const VALID_TRANSITIONS: Record<string, TaskState[]> = {
+  pending:   ["active", "cancelled"],
+  active:    ["completed", "failed", "timeout", "blocked"],
+  blocked:   ["active", "cancelled"],
+  completed: [],
+  failed:    [],
+  timeout:   [],
+  cancelled: [],
+};
+
+// -----------------------------------------------------------------------------
+// File Naming Conventions
+// -----------------------------------------------------------------------------
+
+/** Directory where a task file lives based on its state */
+export const STATE_DIRECTORY: Record<TaskState, string> = {
+  pending:   "inbox",
+  active:    "active",
+  completed: "done",
+  failed:    "done",
+  timeout:   "done",
+  blocked:   "blocked",
+  cancelled: "done",
+};
+
+/** File extensions by message type */
+export const FILE_EXTENSIONS = {
+  intent: ".intent.json",
+  result: ".result.json",
+} as const;
+
+/** Default mailbox directory names */
+export const MAILBOX_DEFAULTS = {
+  active: "active",
+  done: "done",
+  inbox: "inbox",
+  blocked: "blocked",
+} as const;

package/src/nop/registry.ts

@@ -0,0 +1,13 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+import { FrameRegistry } from "../core/registry.js";
+import { FrameType } from "../core/frames.js";
+import { AlignStreamFrame, DelegateFrame, SyncFrame, TaskFrame } from "./frames.js";
+
+export function registerNopFrames(registry: FrameRegistry): void {
+  registry.register(FrameType.TASK,         TaskFrame);
+  registry.register(FrameType.DELEGATE,     DelegateFrame);
+  registry.register(FrameType.SYNC,         SyncFrame);
+  registry.register(FrameType.ALIGN_STREAM, AlignStreamFrame);
+}

package/src/nwp/client.ts

@@ -0,0 +1,114 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * NwpClient — async HTTP-mode client for NPS Neural Web Protocol nodes (NPS-2).
+ */
+
+import { NpsFrameCodec } from "../core/codec.js";
+import { EncodingTier } from "../core/frames.js";
+import { FrameRegistry } from "../core/registry.js";
+import { registerNcpFrames } from "../ncp/registry.js";
+import { CapsFrame } from "../ncp/frames.js";
+import type { StreamFrame } from "../ncp/frames.js";
+import { registerNwpFrames } from "./registry.js";
+import { ActionFrame, asyncActionResponseFromDict } from "./frames.js";
+import type { AnchorFrame } from "../ncp/frames.js";
+import type { QueryFrame, AsyncActionResponse } from "./frames.js";
+
+const CONTENT_TYPE = "application/x-nps-frame";
+
+export class NwpClient {
+  private readonly _baseUrl: string;
+  private readonly _codec:   NpsFrameCodec;
+  private readonly _tier:    EncodingTier;
+
+  constructor(
+    baseUrl: string,
+    options: { defaultTier?: EncodingTier; maxPayload?: number; registry?: FrameRegistry } = {},
+  ) {
+    this._baseUrl = baseUrl.replace(/\/$/, "");
+    this._tier    = options.defaultTier ?? EncodingTier.MSGPACK;
+
+    const registry = options.registry ?? (() => {
+      const r = new FrameRegistry();
+      registerNcpFrames(r);
+      registerNwpFrames(r);
+      return r;
+    })();
+    const codecOpts = options.maxPayload !== undefined ? { maxPayload: options.maxPayload } : {};
+    this._codec = new NpsFrameCodec(registry, codecOpts);
+  }
+
+  async sendAnchor(frame: AnchorFrame): Promise<void> {
+    const wire = this._codec.encode(frame, { overrideTier: this._tier });
+    const res  = await fetch(`${this._baseUrl}/anchor`, {
+      method:  "POST",
+      body:    wire,
+      headers: { "Content-Type": CONTENT_TYPE, "Accept": CONTENT_TYPE },
+    });
+    if (!res.ok) throw new Error(`NWP /anchor failed: HTTP ${res.status}`);
+  }
+
+  async query(frame: QueryFrame): Promise<CapsFrame> {
+    const wire = this._codec.encode(frame, { overrideTier: this._tier });
+    const res  = await fetch(`${this._baseUrl}/query`, {
+      method:  "POST",
+      body:    wire,
+      headers: { "Content-Type": CONTENT_TYPE, "Accept": CONTENT_TYPE },
+    });
+    if (!res.ok) throw new Error(`NWP /query failed: HTTP ${res.status}`);
+
+    const buf    = new Uint8Array(await res.arrayBuffer());
+    const result = this._codec.decode(buf);
+    if (!(result instanceof CapsFrame)) {
+      throw new TypeError(`Expected CapsFrame from /query, got ${result.constructor.name}.`);
+    }
+    return result;
+  }
+
+  async *stream(frame: QueryFrame): AsyncGenerator<StreamFrame> {
+    const wire = this._codec.encode(frame, { overrideTier: this._tier });
+    const res  = await fetch(`${this._baseUrl}/stream`, {
+      method:  "POST",
+      body:    wire,
+      headers: { "Content-Type": CONTENT_TYPE, "Accept": CONTENT_TYPE },
+    });
+    if (!res.ok) throw new Error(`NWP /stream failed: HTTP ${res.status}`);
+    if (res.body === null) return;
+
+    const { StreamFrame: SF } = await import("../ncp/frames.js");
+
+    for await (const chunk of res.body) {
+      const bytes = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk as ArrayBuffer);
+      if (bytes.length === 0) continue;
+      const result = this._codec.decode(bytes);
+      if (!(result instanceof SF)) {
+        throw new TypeError(`Expected StreamFrame from /stream, got ${result.constructor.name}.`);
+      }
+      yield result;
+      if (result.isLast) break;
+    }
+  }
+
+  async invoke(frame: ActionFrame): Promise<unknown> {
+    const wire = this._codec.encode(frame, { overrideTier: this._tier });
+    const res  = await fetch(`${this._baseUrl}/invoke`, {
+      method:  "POST",
+      body:    wire,
+      headers: { "Content-Type": CONTENT_TYPE, "Accept": CONTENT_TYPE },
+    });
+    if (!res.ok) throw new Error(`NWP /invoke failed: HTTP ${res.status}`);
+
+    if (frame.async_) {
+      return asyncActionResponseFromDict(await res.json() as Record<string, unknown>) as AsyncActionResponse;
+    }
+
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType.includes(CONTENT_TYPE)) {
+      const buf = new Uint8Array(await res.arrayBuffer());
+      return this._codec.decode(buf);
+    }
+    return res.json();
+  }
+}

package/src/nwp/frames.ts

@@ -0,0 +1,116 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+import { EncodingTier, FrameType } from "../core/frames.js";
+import type { NpsFrame } from "../core/codec.js";
+
+// ── Filter DSL ────────────────────────────────────────────────────────────────
+
+export interface QueryOrderClause {
+  field: string;
+  dir:   "asc" | "desc";
+}
+
+export interface VectorSearchOptions {
+  vector:      readonly number[];
+  topK?:       number;
+  minScore?:   number;
+  vectorField?: string;
+}
+
+// ── QueryFrame ────────────────────────────────────────────────────────────────
+
+export class QueryFrame implements NpsFrame {
+  readonly frameType     = FrameType.QUERY;
+  readonly preferredTier = EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly anchorRef?:    string,
+    public readonly filter?:       Record<string, unknown>,
+    public readonly limit?:        number,
+    public readonly offset?:       number,
+    public readonly orderBy?:      readonly QueryOrderClause[],
+    public readonly fields?:       readonly string[],
+    public readonly vectorSearch?: VectorSearchOptions,
+    public readonly depth?:        number,
+  ) {}
+
+  toDict(): Record<string, unknown> {
+    return {
+      anchor_ref:    this.anchorRef    ?? null,
+      filter:        this.filter       ?? null,
+      limit:         this.limit        ?? null,
+      offset:        this.offset       ?? null,
+      order_by:      this.orderBy      ?? null,
+      fields:        this.fields       ?? null,
+      vector_search: this.vectorSearch ?? null,
+      depth:         this.depth        ?? null,
+    };
+  }
+
+  static fromDict(data: Record<string, unknown>): QueryFrame {
+    return new QueryFrame(
+      (data["anchor_ref"]    as string  | null) ?? undefined,
+      (data["filter"]        as Record<string, unknown> | null) ?? undefined,
+      (data["limit"]         as number  | null) ?? undefined,
+      (data["offset"]        as number  | null) ?? undefined,
+      (data["order_by"]      as QueryOrderClause[] | null) ?? undefined,
+      (data["fields"]        as string[] | null) ?? undefined,
+      (data["vector_search"] as VectorSearchOptions | null) ?? undefined,
+      (data["depth"]         as number  | null) ?? undefined,
+    );
+  }
+}
+
+// ── ActionFrame ───────────────────────────────────────────────────────────────
+
+export class ActionFrame implements NpsFrame {
+  readonly frameType     = FrameType.ACTION;
+  readonly preferredTier = EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly actionId:        string,
+    public readonly params?:         Record<string, unknown>,
+    public readonly async_?:         boolean,
+    public readonly idempotencyKey?: string,
+    public readonly timeoutMs?:      number,
+  ) {}
+
+  toDict(): Record<string, unknown> {
+    return {
+      action_id:       this.actionId,
+      params:          this.params          ?? null,
+      async:           this.async_          ?? false,
+      idempotency_key: this.idempotencyKey  ?? null,
+      timeout_ms:      this.timeoutMs       ?? null,
+    };
+  }
+
+  static fromDict(data: Record<string, unknown>): ActionFrame {
+    return new ActionFrame(
+      data["action_id"]       as string,
+      (data["params"]          as Record<string, unknown> | null) ?? undefined,
+      (data["async"]           as boolean | null) ?? undefined,
+      (data["idempotency_key"] as string  | null) ?? undefined,
+      (data["timeout_ms"]      as number  | null) ?? undefined,
+    );
+  }
+}
+
+// ── AsyncActionResponse ───────────────────────────────────────────────────────
+
+export interface AsyncActionResponse {
+  taskId:    string;
+  status:    string;
+  pollUrl?:  string | undefined;
+}
+
+export function asyncActionResponseFromDict(data: Record<string, unknown>): AsyncActionResponse {
+  const r: AsyncActionResponse = {
+    taskId: data["task_id"] as string,
+    status: data["status"]  as string,
+  };
+  const pollUrl = data["poll_url"] as string | null | undefined;
+  if (pollUrl != null) r.pollUrl = pollUrl;
+  return r;
+}

package/src/nwp/index.ts

@@ -0,0 +1,6 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./frames.js";
+export * from "./registry.js";
+export * from "./client.js";

package/src/nwp/registry.ts

@@ -0,0 +1,11 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+import { FrameRegistry } from "../core/registry.js";
+import { FrameType } from "../core/frames.js";
+import { ActionFrame, QueryFrame } from "./frames.js";
+
+export function registerNwpFrames(registry: FrameRegistry): void {
+  registry.register(FrameType.QUERY,  QueryFrame);
+  registry.register(FrameType.ACTION, ActionFrame);
+}

package/src/setup.ts

@@ -0,0 +1,32 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Registry factory helpers — lives outside core/ to avoid circular imports.
+ * Use createDefaultRegistry() for NCP-only, createFullRegistry() for all protocols.
+ */
+
+import { FrameRegistry } from "./core/registry.js";
+import { registerNcpFrames } from "./ncp/registry.js";
+import { registerNwpFrames } from "./nwp/registry.js";
+import { registerNipFrames } from "./nip/registry.js";
+import { registerNdpFrames } from "./ndp/registry.js";
+import { registerNopFrames } from "./nop/registry.js";
+
+/** NCP frames only (ANCHOR, DIFF, STREAM, CAPS, ERROR). */
+export function createDefaultRegistry(): FrameRegistry {
+  const r = new FrameRegistry();
+  registerNcpFrames(r);
+  return r;
+}
+
+/** All 5 protocols (NCP + NWP + NIP + NDP + NOP). */
+export function createFullRegistry(): FrameRegistry {
+  const r = new FrameRegistry();
+  registerNcpFrames(r);
+  registerNwpFrames(r);
+  registerNipFrames(r);
+  registerNdpFrames(r);
+  registerNopFrames(r);
+  return r;
+}