@labacacia/nps-sdk 1.0.0-alpha.6 → 1.0.0-alpha.8

package/src/nop/frames.ts

@@ -1,181 +0,0 @@
-// 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";
-import type { AggregateStrategy, TaskContext, TaskDag, TaskPriority } from "./models.js";
-
-// ── TaskFrame ─────────────────────────────────────────────────────────────────
-
-export class TaskFrame implements NpsFrame {
-  readonly frameType     = FrameType.TASK;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly taskId:       string,
-    public readonly dag:          TaskDag,
-    public readonly timeoutMs?:   number,
-    public readonly callbackUrl?: string,
-    public readonly context?:     TaskContext,
-    public readonly priority?:    TaskPriority,
-    public readonly depth?:       number,
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      task_id:      this.taskId,
-      dag:          this.dag,
-      timeout_ms:   this.timeoutMs   ?? null,
-      callback_url: this.callbackUrl ?? null,
-      context:      this.context     ?? null,
-      priority:     this.priority    ?? null,
-      depth:        this.depth       ?? null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): TaskFrame {
-    return new TaskFrame(
-      data["task_id"]      as string,
-      data["dag"]          as TaskDag,
-      (data["timeout_ms"]   as number | null) ?? undefined,
-      (data["callback_url"] as string | null) ?? undefined,
-      (data["context"]      as TaskContext | null) ?? undefined,
-      (data["priority"]     as TaskPriority | null) ?? undefined,
-      (data["depth"]        as number | null) ?? undefined,
-    );
-  }
-}
-
-// ── DelegateFrame ─────────────────────────────────────────────────────────────
-
-export class DelegateFrame implements NpsFrame {
-  readonly frameType     = FrameType.DELEGATE;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly taskId:         string,
-    public readonly subtaskId:      string,
-    public readonly action:         string,
-    public readonly agentNid:       string,
-    public readonly inputs?:        Record<string, unknown>,
-    public readonly params?:        Record<string, unknown>,
-    public readonly idempotencyKey?: string,
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      task_id:         this.taskId,
-      subtask_id:      this.subtaskId,
-      action:          this.action,
-      agent_nid:       this.agentNid,
-      inputs:          this.inputs          ?? null,
-      params:          this.params          ?? null,
-      idempotency_key: this.idempotencyKey  ?? null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): DelegateFrame {
-    return new DelegateFrame(
-      data["task_id"]         as string,
-      data["subtask_id"]      as string,
-      data["action"]          as string,
-      data["agent_nid"]       as string,
-      (data["inputs"]          as Record<string, unknown> | null) ?? undefined,
-      (data["params"]          as Record<string, unknown> | null) ?? undefined,
-      (data["idempotency_key"] as string | null) ?? undefined,
-    );
-  }
-}
-
-// ── SyncFrame ─────────────────────────────────────────────────────────────────
-
-export class SyncFrame implements NpsFrame {
-  readonly frameType     = FrameType.SYNC;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly taskId:      string,
-    public readonly syncId:      string,
-    public readonly waitFor:     readonly string[],
-    public readonly minRequired: number = 0,
-    public readonly aggregate:   AggregateStrategy | string = "merge",
-    public readonly timeoutMs?:  number,
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      task_id:      this.taskId,
-      sync_id:      this.syncId,
-      wait_for:     this.waitFor,
-      min_required: this.minRequired,
-      aggregate:    this.aggregate,
-      timeout_ms:   this.timeoutMs ?? null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): SyncFrame {
-    return new SyncFrame(
-      data["task_id"]      as string,
-      data["sync_id"]      as string,
-      data["wait_for"]     as string[],
-      (data["min_required"] as number) ?? 0,
-      (data["aggregate"]    as string) ?? "merge",
-      (data["timeout_ms"]   as number | null) ?? undefined,
-    );
-  }
-}
-
-// ── StreamError ───────────────────────────────────────────────────────────────
-
-export interface StreamError {
-  errorCode: string;
-  message?:  string;
-}
-
-// ── AlignStreamFrame ──────────────────────────────────────────────────────────
-
-export class AlignStreamFrame implements NpsFrame {
-  readonly frameType     = FrameType.ALIGN_STREAM;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly streamId:   string,
-    public readonly taskId:     string,
-    public readonly subtaskId:  string,
-    public readonly seq:        number,
-    public readonly isFinal:    boolean,
-    public readonly senderNid:  string,
-    public readonly data?:      Record<string, unknown>,
-    public readonly error?:     StreamError,
-    public readonly windowSize?: number,
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      stream_id:   this.streamId,
-      task_id:     this.taskId,
-      subtask_id:  this.subtaskId,
-      seq:         this.seq,
-      is_final:    this.isFinal,
-      sender_nid:  this.senderNid,
-      data:        this.data        ?? null,
-      error:       this.error ? { error_code: this.error.errorCode, message: this.error.message ?? null } : null,
-      window_size: this.windowSize  ?? null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): AlignStreamFrame {
-    const rawError = data["error"] as { error_code: string; message?: string } | null;
-    return new AlignStreamFrame(
-      data["stream_id"]  as string,
-      data["task_id"]    as string,
-      data["subtask_id"] as string,
-      data["seq"]        as number,
-      data["is_final"]   as boolean,
-      data["sender_nid"] as string,
-      (data["data"]        as Record<string, unknown> | null) ?? undefined,
-      rawError ? { errorCode: rawError.error_code, ...(rawError.message != null ? { message: rawError.message } : {}) } : undefined,
-      (data["window_size"] as number | null) ?? undefined,
-    );
-  }
-}

package/src/nop/models.ts

@@ -1,79 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-export enum TaskState {
-  PENDING       = "pending",
-  PREFLIGHT     = "preflight",
-  RUNNING       = "running",
-  WAITING_SYNC  = "waiting_sync",
-  COMPLETED     = "completed",
-  FAILED        = "failed",
-  CANCELLED     = "cancelled",
-  SKIPPED       = "skipped",
-}
-
-export enum TaskPriority {
-  LOW    = "low",
-  NORMAL = "normal",
-  HIGH   = "high",
-}
-
-export enum BackoffStrategy {
-  FIXED       = "fixed",
-  LINEAR      = "linear",
-  EXPONENTIAL = "exponential",
-}
-
-export enum AggregateStrategy {
-  MERGE      = "merge",
-  FIRST      = "first",
-  FASTEST_K  = "fastest_k",
-  ALL        = "all",
-}
-
-export interface RetryPolicy {
-  maxRetries:   number;
-  backoff:      BackoffStrategy;
-  baseDelayMs?: number;
-  maxDelayMs?:  number;
-}
-
-export function computeDelayMs(policy: RetryPolicy, attempt: number): number {
-  const base = policy.baseDelayMs ?? 1000;
-  const cap  = policy.maxDelayMs  ?? 30_000;
-  let delay: number;
-  switch (policy.backoff) {
-    case BackoffStrategy.FIXED:       delay = base; break;
-    case BackoffStrategy.LINEAR:      delay = base * (attempt + 1); break;
-    case BackoffStrategy.EXPONENTIAL: delay = base * Math.pow(2, attempt); break;
-  }
-  return Math.min(delay, cap);
-}
-
-export interface TaskContext {
-  sessionKey?:    string;
-  requesterNid?:  string;
-  traceId?:       string;
-}
-
-export interface DagNode {
-  id:             string;
-  action:         string;
-  agent:          string;
-  inputFrom?:     readonly string[];
-  inputMapping?:  Record<string, string>;
-  timeoutMs?:     number;
-  retryPolicy?:   RetryPolicy;
-  condition?:     string;
-  minRequired?:   number;
-}
-
-export interface DagEdge {
-  from: string;
-  to:   string;
-}
-
-export interface TaskDag {
-  nodes: readonly DagNode[];
-  edges: readonly DagEdge[];
-}

package/src/nop/nop-types.ts

@@ -1,208 +0,0 @@
-// 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

@@ -1,13 +0,0 @@
-// 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

@@ -1,114 +0,0 @@
-// 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 as BodyInit,
-      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 as BodyInit,
-      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 as BodyInit,
-      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 as BodyInit,
-      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();
-  }
-}