nemo-fabric-adapters-common 0.0.0 → 0.3.0-beta.2

package/README.md

@@ -1,9 +1,44 @@
-# nemo-fabric-adapters-common
+<!--
+SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+SPDX-License-Identifier: Apache-2.0
+-->
 
-This `0.0.0` release is an inert registry bootstrap for the
-`nemo-fabric-adapters-common` package name. It contains no runtime code and is
-not a supported NVIDIA NeMo Fabric adapter release.
+# NVIDIA NeMo Fabric TypeScript Adapter Utilities
 
-Supported releases are published from the
-[NVIDIA NeMo Fabric repository](https://github.com/NVIDIA/NeMo-Fabric) through
-npm trusted publishing.
+This package provides the persistent process lifecycle host shared by
+TypeScript adapters. It validates southbound configuration, requests, runtime
+context, and terminal results against the schemas bundled with
+`nemo-fabric-adapter-contract`.
+
+The host owns JSONL framing, ordered `start`/`invoke`/`stop` dispatch, runtime
+identity checks, safe lifecycle failures, and cleanup after partial startup or
+end of input. Adapter implementations own only target translation and target
+state.
+
+The following example starts and serves a `MyAdapterRuntime` instance:
+
+```typescript
+import { serve } from "nemo-fabric-adapters-common";
+
+await serve(() => new MyAdapterRuntime());
+```
+
+The factory may return a runtime directly or resolve one asynchronously. The
+host begins reading lifecycle input before it awaits asynchronous adapter setup.
+
+This package is intended to be published as the shared runtime dependency for
+TypeScript adapters. Its public API will be versioned independently from the
+adapters that use it.
+
+## Dependency Rationale
+
+`ajv` enforces the canonical JSON Schema contracts at the process boundary;
+hand-written validators were rejected because they could drift from those
+schemas. `nemo-fabric-adapter-contract` supplies the shared types and packaged
+schemas; copying them into this package would create another contract authority.
+
+`typescript` and `@types/node` are exact-pinned build inputs. They provide the
+compiler and Node.js declarations without entering the published production
+dependency graph. The private TypeScript workspace uses a local
+`nemo-fabric-adapter-contract` file link so source builds test the checked-out
+contract. Published package manifests use the registry version instead.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { LifecycleError, serve, type AdapterRuntime, type AdapterRuntimeFactory, type AdapterStartInput, type LifecycleHostOptions, } from "./lifecycle.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Public entry point for TypeScript process adapters. It exposes the lifecycle
+// host, adapter-facing runtime interfaces, and normalized lifecycle errors
+// without exposing the host's internal protocol machinery.
+export { LifecycleError, serve, } from "./lifecycle.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,49 @@
+import type { Readable, Writable } from "node:stream";
+import type { AgentConfig, AgentRunRequest, AgentRunResult, JsonObject, RuntimeContext } from "nemo-fabric-adapter-contract";
+export interface AdapterStartInput {
+    agentName: string;
+    baseDir: string;
+    config: AgentConfig;
+    runtimeContext: RuntimeContext;
+    capabilityPlan?: JsonObject;
+    telemetryPlan?: JsonObject;
+}
+export interface AdapterRuntime {
+    start(input: AdapterStartInput): Promise<void>;
+    invoke(request: AgentRunRequest, context: RuntimeContext): Promise<AgentRunResult>;
+    stop(): Promise<void>;
+}
+export type AdapterRuntimeFactory = () => AdapterRuntime | Promise<AdapterRuntime>;
+export interface LifecycleHostOptions {
+    input?: Readable;
+    output?: Writable;
+    diagnostics?: Writable;
+}
+export declare class LifecycleError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly metadata?: JsonObject;
+    constructor(code: string, message: string, options?: {
+        retryable?: boolean;
+        metadata?: JsonObject;
+    });
+}
+/**
+ * Serve the persistent, newline-delimited lifecycle protocol for one adapter runtime.
+ *
+ * The host reads one JSON request per input line, validates normalized contract
+ * payloads, and writes exactly one normalized response per output line. A valid
+ * start request creates the runtime through `factory`; subsequent invoke and
+ * stop requests must carry the same runtime ID. The host validates adapter
+ * results, converts adapter failures into stable lifecycle errors, and prevents
+ * further invocation after an unexpected adapter or response-encoding failure.
+ *
+ * When the protocol uses process stdout, other stdout writes are redirected to
+ * stderr so logs cannot corrupt the response stream. The active runtime is
+ * cleaned up after a stop request, a failed start, or input termination. Tests
+ * can provide isolated input, output, and diagnostic streams through `options`.
+ *
+ * @param factory Creates the adapter-owned runtime for a valid start request.
+ * @param options Overrides the process streams, primarily for embedding and tests.
+ */
+export declare function serve(factory: AdapterRuntimeFactory, options?: LifecycleHostOptions): Promise<void>;

package/dist/lifecycle.js

@@ -0,0 +1,293 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Shared process-adapter lifecycle host. It validates newline-delimited
+// lifecycle requests, owns one adapter runtime, dispatches start, invoke, and
+// stop operations, and returns normalized responses while keeping diagnostics
+// off the protocol output stream.
+import { createRequire } from "node:module";
+import { createInterface } from "node:readline";
+export class LifecycleError extends Error {
+    code;
+    retryable;
+    metadata;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = "LifecycleError";
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+        this.metadata = options.metadata;
+    }
+}
+class AdapterCallError extends LifecycleError {
+}
+const require = createRequire(import.meta.url);
+const Ajv2020 = require("ajv/dist/2020.js").default;
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+ajv.addFormat("uint32", {
+    type: "number",
+    validate: (value) => Number.isInteger(value) && value >= 0 && value <= 0xffff_ffff,
+});
+ajv.addFormat("uint64", {
+    type: "number",
+    validate: (value) => Number.isSafeInteger(value) && value >= 0,
+});
+ajv.addFormat("double", {
+    type: "number",
+    validate: (value) => Number.isFinite(value),
+});
+const validateAgentConfig = compileSchema("agent-config");
+const validateAgentRunRequest = compileSchema("agent-run-request");
+const validateAgentRunResult = compileSchema("agent-run-result");
+const validateRuntimeContext = compileSchema("runtime-context");
+function compileSchema(name) {
+    const schema = require(`nemo-fabric-adapter-contract/schemas/${name}`);
+    return ajv.compile(schema);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireRecord(value, code, message) {
+    if (!isRecord(value)) {
+        throw new LifecycleError(code, message);
+    }
+    return value;
+}
+function validate(validator, value, code, message) {
+    if (!validator(value)) {
+        throw new LifecycleError(code, message);
+    }
+    return value;
+}
+function runtimeId(operation, payload) {
+    const value = operation === "stop"
+        ? payload.runtime_id
+        : isRecord(payload.runtime_context)
+            ? payload.runtime_context.runtime_id
+            : undefined;
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function decodeRequest(value) {
+    const message = requireRecord(value, "lifecycle_invalid_request", "Lifecycle request must be an object");
+    const operation = message.operation;
+    if (operation !== "start" && operation !== "invoke" && operation !== "stop") {
+        throw new LifecycleError("lifecycle_invalid_operation", "Unknown lifecycle operation");
+    }
+    return {
+        operation,
+        payload: requireRecord(message.payload, "lifecycle_invalid_payload", "Lifecycle payload must be an object"),
+    };
+}
+function decodeStart(payload) {
+    if (typeof payload.agent_name !== "string" || payload.agent_name.length === 0) {
+        throw new LifecycleError("lifecycle_invalid_start", "Start payload is missing an agent name");
+    }
+    if (typeof payload.base_dir !== "string" || payload.base_dir.length === 0) {
+        throw new LifecycleError("lifecycle_invalid_start", "Start payload is missing a base directory");
+    }
+    const config = validate(validateAgentConfig, payload.config, "lifecycle_invalid_config", "Adapter config does not match its typed contract");
+    const context = validate(validateRuntimeContext, payload.runtime_context, "lifecycle_invalid_context", "Runtime context does not match its typed contract");
+    const capabilityPlan = payload.capability_plan;
+    const telemetryPlan = payload.telemetry_plan;
+    if (capabilityPlan !== undefined && !isRecord(capabilityPlan)) {
+        throw new LifecycleError("lifecycle_invalid_start", "Capability plan must be an object");
+    }
+    if (telemetryPlan !== undefined && !isRecord(telemetryPlan)) {
+        throw new LifecycleError("lifecycle_invalid_start", "Telemetry plan must be an object");
+    }
+    return {
+        agentName: payload.agent_name,
+        baseDir: payload.base_dir,
+        config,
+        runtimeContext: context,
+        capabilityPlan: capabilityPlan,
+        telemetryPlan: telemetryPlan,
+    };
+}
+function decodeInvocation(payload) {
+    return {
+        request: validate(validateAgentRunRequest, payload.request, "lifecycle_invalid_request", "Invocation request does not match its typed contract"),
+        context: validate(validateRuntimeContext, payload.runtime_context, "lifecycle_invalid_context", "Runtime context does not match its typed contract"),
+    };
+}
+async function callAdapter(operation, call) {
+    try {
+        return await call();
+    }
+    catch (error) {
+        if (error instanceof LifecycleError) {
+            throw new AdapterCallError(error.code, error.message, {
+                retryable: error.retryable,
+                metadata: error.metadata,
+            });
+        }
+        throw new AdapterCallError(`lifecycle_adapter_${operation}_failed`, `Adapter failed during lifecycle ${operation}`);
+    }
+}
+async function stopQuietly(runtime, diagnostics) {
+    try {
+        await callAdapter("stop", () => runtime.stop());
+    }
+    catch (error) {
+        diagnostics.write(`Adapter cleanup failed: ${error instanceof Error ? error.message : "unknown error"}\n`);
+    }
+}
+function success(operation, output = null) {
+    return { operation, outcome: { status: "succeeded", output } };
+}
+function failure(operation, error) {
+    const stage = operation === "invoke" ? "invoke" : operation;
+    const detail = {
+        stage,
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+    };
+    if (error.metadata !== undefined) {
+        detail.metadata = error.metadata;
+    }
+    return { operation, outcome: { status: "failed", error: detail } };
+}
+async function dispatch(state, factory, request, diagnostics) {
+    const messageRuntimeId = runtimeId(request.operation, request.payload);
+    if (messageRuntimeId === undefined) {
+        throw new LifecycleError("lifecycle_invalid_runtime", "Lifecycle payload is missing a runtime ID");
+    }
+    if (request.operation === "start") {
+        if (state.runtime !== undefined) {
+            throw new LifecycleError("lifecycle_already_started", "Lifecycle host already owns a runtime");
+        }
+        let candidate;
+        try {
+            candidate = await callAdapter("start", factory);
+            const active = candidate;
+            await callAdapter("start", () => active.start(decodeStart(request.payload)));
+        }
+        catch (error) {
+            if (candidate !== undefined) {
+                await stopQuietly(candidate, diagnostics);
+            }
+            throw error;
+        }
+        state.runtime = candidate;
+        state.runtimeId = messageRuntimeId;
+        state.failed = false;
+        return success("start");
+    }
+    if (state.runtime === undefined || state.runtimeId === undefined) {
+        throw new LifecycleError("lifecycle_not_started", "Lifecycle host has not started a runtime");
+    }
+    if (state.runtimeId !== messageRuntimeId) {
+        throw new LifecycleError("lifecycle_runtime_mismatch", "Lifecycle payload does not match the active runtime");
+    }
+    if (request.operation === "stop") {
+        const active = state.runtime;
+        await callAdapter("stop", () => active.stop());
+        state.runtime = undefined;
+        state.runtimeId = undefined;
+        state.failed = false;
+        return success("stop");
+    }
+    if (state.failed) {
+        throw new LifecycleError("lifecycle_runtime_failed", "Lifecycle runtime cannot accept another invocation");
+    }
+    const { request: invocation, context } = decodeInvocation(request.payload);
+    try {
+        const result = await callAdapter("invoke", () => state.runtime.invoke(invocation, context));
+        validate(validateAgentRunResult, result, "lifecycle_invalid_response", "Adapter returned an invalid AgentRunResult");
+        return success("invoke", result);
+    }
+    catch (error) {
+        if (error instanceof AdapterCallError ||
+            (error instanceof LifecycleError && error.code === "lifecycle_invalid_response")) {
+            state.failed = true;
+        }
+        throw error;
+    }
+}
+function parseLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        throw new LifecycleError("lifecycle_invalid_request", "Lifecycle request is not valid JSON");
+    }
+}
+/**
+ * Serve the persistent, newline-delimited lifecycle protocol for one adapter runtime.
+ *
+ * The host reads one JSON request per input line, validates normalized contract
+ * payloads, and writes exactly one normalized response per output line. A valid
+ * start request creates the runtime through `factory`; subsequent invoke and
+ * stop requests must carry the same runtime ID. The host validates adapter
+ * results, converts adapter failures into stable lifecycle errors, and prevents
+ * further invocation after an unexpected adapter or response-encoding failure.
+ *
+ * When the protocol uses process stdout, other stdout writes are redirected to
+ * stderr so logs cannot corrupt the response stream. The active runtime is
+ * cleaned up after a stop request, a failed start, or input termination. Tests
+ * can provide isolated input, output, and diagnostic streams through `options`.
+ *
+ * @param factory Creates the adapter-owned runtime for a valid start request.
+ * @param options Overrides the process streams, primarily for embedding and tests.
+ */
+export async function serve(factory, options = {}) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    const diagnostics = options.diagnostics ?? process.stderr;
+    const protocolWrite = output.write.bind(output);
+    const originalStdoutWrite = process.stdout.write;
+    const redirectsStdout = output === process.stdout;
+    if (redirectsStdout) {
+        process.stdout.write = process.stderr.write.bind(process.stderr);
+    }
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    const state = { failed: false };
+    try {
+        for await (const line of lines) {
+            let operation = "start";
+            let shouldStop = false;
+            let response;
+            try {
+                const parsed = parseLine(line);
+                if (isRecord(parsed) && typeof parsed.operation === "string") {
+                    operation = parsed.operation;
+                }
+                const request = decodeRequest(parsed);
+                operation = request.operation;
+                response = await dispatch(state, factory, request, diagnostics);
+                shouldStop = operation === "stop";
+            }
+            catch (error) {
+                const lifecycleError = error instanceof LifecycleError
+                    ? error
+                    : new LifecycleError("lifecycle_invalid_request", "Invalid lifecycle request");
+                response = failure(operation, lifecycleError);
+                shouldStop = operation === "start" || operation === "stop";
+            }
+            let encoded;
+            try {
+                encoded = JSON.stringify(response);
+            }
+            catch {
+                if (operation === "invoke") {
+                    state.failed = true;
+                }
+                response = failure(operation, new LifecycleError("lifecycle_invalid_response", "Adapter response could not be encoded as lifecycle JSON"));
+                encoded = JSON.stringify(response);
+            }
+            protocolWrite(`${encoded}\n`);
+            if (shouldStop) {
+                break;
+            }
+        }
+    }
+    finally {
+        lines.close();
+        if (state.runtime !== undefined) {
+            await stopQuietly(state.runtime, diagnostics);
+        }
+        if (redirectsStdout) {
+            process.stdout.write = originalStdoutWrite;
+        }
+    }
+}

package/package.json

@@ -1,14 +1,52 @@
 {
   "name": "nemo-fabric-adapters-common",
-  "version": "0.0.0",
-  "description": "Registry bootstrap for the NVIDIA NeMo Fabric TypeScript adapter package.",
+  "version": "0.3.0-beta.2",
+  "description": "Shared TypeScript lifecycle host for NVIDIA NeMo Fabric adapters.",
   "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "files": [
+    "dist",
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "pack:check": "npm run build && node ../scripts/check-package.mjs",
+    "prepack": "npm run build",
+    "test": "npm run clean && npm run build && node --test test/*.test.mjs"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NVIDIA/NeMo-Fabric.git",
+    "directory": "adapters/typescript/common"
+  },
+  "bugs": {
+    "url": "https://github.com/NVIDIA/NeMo-Fabric/issues"
+  },
+  "homepage": "https://github.com/NVIDIA/NeMo-Fabric/tree/main/adapters/typescript/common#readme",
+  "engines": {
+    "node": ">=20.18.3"
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "nemo-fabric-adapter-contract": "0.3.0-beta.2"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.19",
+    "typescript": "5.6.3"
   }
 }