orbit-bus 0.1.1

package/dist/src/envelope.js

@@ -0,0 +1,92 @@
+import { OrbitError } from "./errors.js";
+import { randomId, sha256, stableStringify } from "./util.js";
+const SCHEMA_VERSION = "1.0";
+export function hashEnvelopeFields(input) {
+    return sha256(stableStringify(input));
+}
+export function createEnvelope(params) {
+    const base = {
+        id: randomId(),
+        run_id: params.runId ?? randomId(),
+        ts: new Date().toISOString(),
+        kind: params.kind,
+        schema_version: SCHEMA_VERSION,
+        payload: params.payload,
+        data_pack: params.dataPack,
+        provenance: params.provenance,
+        cost: params.cost,
+        a2a: params.a2a
+    };
+    return { ...base, hash: hashEnvelopeFields(base) };
+}
+function validateA2A(input) {
+    if (input === undefined)
+        return undefined;
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new OrbitError("INVALID_ENVELOPE", "a2a must be an object");
+    }
+    const raw = input;
+    const strOrUndefined = (value, field) => {
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== "string" || !value) {
+            throw new OrbitError("INVALID_ENVELOPE", `a2a.${field} must be a non-empty string`);
+        }
+        return value;
+    };
+    if (raw.capabilities !== undefined) {
+        if (!Array.isArray(raw.capabilities) || raw.capabilities.some((v) => typeof v !== "string" || !v)) {
+            throw new OrbitError("INVALID_ENVELOPE", "a2a.capabilities must be a string[]");
+        }
+    }
+    return {
+        task_id: strOrUndefined(raw.task_id, "task_id"),
+        thread_id: strOrUndefined(raw.thread_id, "thread_id"),
+        parent_message_id: strOrUndefined(raw.parent_message_id, "parent_message_id"),
+        capabilities: raw.capabilities,
+        traceparent: strOrUndefined(raw.traceparent, "traceparent"),
+        dedupe_key: strOrUndefined(raw.dedupe_key, "dedupe_key")
+    };
+}
+export function validateEnvelope(input, options) {
+    if (!input || typeof input !== "object") {
+        throw new OrbitError("INVALID_ENVELOPE", "Envelope must be an object");
+    }
+    const env = input;
+    const required = ["id", "run_id", "ts", "kind", "schema_version", "payload", "hash"];
+    for (const key of required) {
+        if (!(key in env))
+            throw new OrbitError("INVALID_ENVELOPE", `Missing envelope field: ${key}`);
+    }
+    if (typeof env.id !== "string" || !env.id)
+        throw new OrbitError("INVALID_ENVELOPE", "id must be a string");
+    if (typeof env.run_id !== "string" || !env.run_id)
+        throw new OrbitError("INVALID_ENVELOPE", "run_id must be a string");
+    if (typeof env.ts !== "string" || Number.isNaN(Date.parse(env.ts)))
+        throw new OrbitError("INVALID_ENVELOPE", "ts must be ISO timestamp");
+    if (typeof env.kind !== "string")
+        throw new OrbitError("INVALID_ENVELOPE", "kind must be string");
+    if (typeof env.schema_version !== "string")
+        throw new OrbitError("INVALID_ENVELOPE", "schema_version must be string");
+    if (typeof env.hash !== "string" || !env.hash)
+        throw new OrbitError("INVALID_ENVELOPE", "hash must be string");
+    const candidate = {
+        id: env.id,
+        run_id: env.run_id,
+        ts: env.ts,
+        kind: env.kind,
+        schema_version: env.schema_version,
+        payload: env.payload,
+        data_pack: env.data_pack,
+        provenance: env.provenance,
+        cost: env.cost,
+        a2a: validateA2A(env.a2a)
+    };
+    if (!options?.skipHashCheck && hashEnvelopeFields(candidate) !== env.hash) {
+        throw new OrbitError("INVALID_ENVELOPE_HASH", "Envelope hash mismatch");
+    }
+    return {
+        ...env,
+        a2a: candidate.a2a
+    };
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class OrbitError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}

package/dist/src/errors.js

@@ -0,0 +1,9 @@
+export class OrbitError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/index.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { run } from "./cli.js";
+import { OrbitError } from "./errors.js";
+run(process.argv.slice(2), process.cwd()).catch((err) => {
+    if (err instanceof OrbitError) {
+        process.stderr.write(`${JSON.stringify({ ok: false, code: err.code, message: err.message, details: err.details })}\n`);
+        process.exit(2);
+    }
+    process.stderr.write(`${JSON.stringify({ ok: false, code: "UNHANDLED", message: err.message })}\n`);
+    process.exit(1);
+});

package/dist/src/jetstream_durable.d.ts

@@ -0,0 +1,4 @@
+export declare function defaultDurableStreamName(subject: string): string;
+export declare function defaultDurableConsumerName(subject: string): string;
+export declare function ensureStreamSubjects(jsm: any, streamName: string, subjects: string[]): Promise<void>;
+export declare function ensureDurableConsumer(jsm: any, streamName: string, durableName: string, filterSubject: string, ackWaitMs: number, maxDeliver: number): Promise<void>;

package/dist/src/jetstream_durable.js

@@ -0,0 +1,51 @@
+import { AckPolicy, DeliverPolicy } from "nats";
+function sanitizeToken(input) {
+    return input.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 80) || "subject";
+}
+export function defaultDurableStreamName(subject) {
+    return `orbit_${sanitizeToken(subject)}_stream`;
+}
+export function defaultDurableConsumerName(subject) {
+    return `orbit_${sanitizeToken(subject)}_consumer`;
+}
+export async function ensureStreamSubjects(jsm, streamName, subjects) {
+    const unique = Array.from(new Set(subjects.filter(Boolean)));
+    if (unique.length === 0)
+        return;
+    try {
+        const info = await jsm.streams.info(streamName);
+        const existing = Array.isArray(info?.config?.subjects) ? info.config.subjects : [];
+        const merged = Array.from(new Set([...existing, ...unique]));
+        if (merged.length !== existing.length) {
+            await jsm.streams.update(streamName, {
+                ...info.config,
+                subjects: merged
+            });
+        }
+        return;
+    }
+    catch {
+        // stream missing; create
+    }
+    await jsm.streams.add({
+        name: streamName,
+        subjects: unique
+    });
+}
+export async function ensureDurableConsumer(jsm, streamName, durableName, filterSubject, ackWaitMs, maxDeliver) {
+    try {
+        await jsm.consumers.info(streamName, durableName);
+        return;
+    }
+    catch {
+        // consumer missing; create
+    }
+    await jsm.consumers.add(streamName, {
+        durable_name: durableName,
+        ack_policy: AckPolicy.Explicit,
+        deliver_policy: DeliverPolicy.All,
+        filter_subject: filterSubject,
+        ack_wait: Math.max(1, Math.floor(ackWaitMs)) * 1_000_000,
+        max_deliver: Math.max(1, Math.floor(maxDeliver))
+    });
+}

package/dist/src/json_schema.d.ts

@@ -0,0 +1,6 @@
+export interface JsonSchemaValidationIssue {
+    path: string;
+    message: string;
+}
+export declare function validateJsonSchema(value: unknown, schema: unknown): JsonSchemaValidationIssue[];
+export declare function assertJsonSchema(value: unknown, schema: unknown, context: string): void;

package/dist/src/json_schema.js

@@ -0,0 +1,154 @@
+import { OrbitError } from "./errors.js";
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function asSchema(value) {
+    return isObject(value) ? value : null;
+}
+function typeMatches(value, expected) {
+    switch (expected) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "object":
+            return isObject(value);
+        case "array":
+            return Array.isArray(value);
+        case "null":
+            return value === null;
+        default:
+            return true;
+    }
+}
+function pushIssue(issues, path, message) {
+    issues.push({ path, message });
+}
+function validateType(value, schema, path, issues) {
+    const rawType = schema.type;
+    if (typeof rawType === "string") {
+        if (!typeMatches(value, rawType)) {
+            pushIssue(issues, path, `expected type ${rawType}`);
+            return false;
+        }
+        return true;
+    }
+    if (Array.isArray(rawType) && rawType.length > 0) {
+        const expected = rawType.filter((v) => typeof v === "string");
+        if (expected.length > 0 && !expected.some((t) => typeMatches(value, t))) {
+            pushIssue(issues, path, `expected one of types: ${expected.join(", ")}`);
+            return false;
+        }
+    }
+    return true;
+}
+function validateEnum(value, schema, path, issues) {
+    const options = schema.enum;
+    if (!Array.isArray(options) || options.length === 0)
+        return;
+    const ok = options.some((option) => JSON.stringify(option) === JSON.stringify(value));
+    if (!ok)
+        pushIssue(issues, path, "value not present in enum");
+}
+function validateString(value, schema, path, issues) {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+        pushIssue(issues, path, `string length must be >= ${schema.minLength}`);
+    }
+    if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+        pushIssue(issues, path, `string length must be <= ${schema.maxLength}`);
+    }
+    if (typeof schema.pattern === "string") {
+        try {
+            const re = new RegExp(schema.pattern);
+            if (!re.test(value))
+                pushIssue(issues, path, `string does not match pattern ${schema.pattern}`);
+        }
+        catch {
+            pushIssue(issues, path, `invalid regex pattern ${schema.pattern}`);
+        }
+    }
+}
+function validateNumber(value, schema, path, issues) {
+    if (typeof schema.minimum === "number" && value < schema.minimum) {
+        pushIssue(issues, path, `number must be >= ${schema.minimum}`);
+    }
+    if (typeof schema.maximum === "number" && value > schema.maximum) {
+        pushIssue(issues, path, `number must be <= ${schema.maximum}`);
+    }
+}
+function validateArray(value, schema, path, issues) {
+    if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+        pushIssue(issues, path, `array length must be >= ${schema.minItems}`);
+    }
+    if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+        pushIssue(issues, path, `array length must be <= ${schema.maxItems}`);
+    }
+    const itemSchema = asSchema(schema.items);
+    if (!itemSchema)
+        return;
+    for (let i = 0; i < value.length; i += 1) {
+        validateAgainstSchema(value[i], itemSchema, `${path}[${i}]`, issues);
+    }
+}
+function validateObject(value, schema, path, issues) {
+    const required = Array.isArray(schema.required) ? schema.required.filter((v) => typeof v === "string") : [];
+    for (const key of required) {
+        if (!(key in value)) {
+            pushIssue(issues, `${path}.${key}`, "required property is missing");
+        }
+    }
+    const props = asSchema(schema.properties) ?? {};
+    const allowAdditional = schema.additionalProperties !== false;
+    for (const key of Object.keys(value)) {
+        const childPath = `${path}.${key}`;
+        const childSchema = asSchema(props[key]);
+        if (!childSchema) {
+            if (!allowAdditional)
+                pushIssue(issues, childPath, "additional properties are not allowed");
+            continue;
+        }
+        validateAgainstSchema(value[key], childSchema, childPath, issues);
+    }
+}
+function validateAgainstSchema(value, schema, path, issues) {
+    validateEnum(value, schema, path, issues);
+    if (Object.prototype.hasOwnProperty.call(schema, "const")) {
+        const constValue = schema.const;
+        if (JSON.stringify(constValue) !== JSON.stringify(value)) {
+            pushIssue(issues, path, "value does not match const");
+        }
+    }
+    const typeOk = validateType(value, schema, path, issues);
+    if (!typeOk)
+        return;
+    if (typeof value === "string") {
+        validateString(value, schema, path, issues);
+    }
+    else if (typeof value === "number") {
+        validateNumber(value, schema, path, issues);
+    }
+    else if (Array.isArray(value)) {
+        validateArray(value, schema, path, issues);
+    }
+    else if (isObject(value)) {
+        validateObject(value, schema, path, issues);
+    }
+}
+export function validateJsonSchema(value, schema) {
+    const schemaObj = asSchema(schema);
+    if (!schemaObj)
+        return [];
+    const issues = [];
+    validateAgainstSchema(value, schemaObj, "$", issues);
+    return issues;
+}
+export function assertJsonSchema(value, schema, context) {
+    const issues = validateJsonSchema(value, schema);
+    if (issues.length === 0)
+        return;
+    throw new OrbitError("SCHEMA_VALIDATION_FAILED", `${context} failed schema validation`, { issues });
+}

package/dist/src/logger.d.ts

@@ -0,0 +1,16 @@
+declare const LEVELS: {
+    readonly debug: 10;
+    readonly info: 20;
+    readonly warn: 30;
+    readonly error: 40;
+};
+export declare class Logger {
+    private readonly level;
+    constructor(level: keyof typeof LEVELS);
+    private emit;
+    debug(msg: string, ctx?: Record<string, unknown>): void;
+    info(msg: string, ctx?: Record<string, unknown>): void;
+    warn(msg: string, ctx?: Record<string, unknown>): void;
+    error(msg: string, ctx?: Record<string, unknown>): void;
+}
+export {};

package/dist/src/logger.js

@@ -0,0 +1,31 @@
+import process from "node:process";
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+export class Logger {
+    level;
+    constructor(level) {
+        this.level = level;
+    }
+    emit(level, msg, ctx) {
+        if (LEVELS[level] < LEVELS[this.level])
+            return;
+        const row = {
+            ts: new Date().toISOString(),
+            level,
+            msg,
+            ...(ctx ?? {})
+        };
+        process.stderr.write(`${JSON.stringify(row)}\n`);
+    }
+    debug(msg, ctx) {
+        this.emit("debug", msg, ctx);
+    }
+    info(msg, ctx) {
+        this.emit("info", msg, ctx);
+    }
+    warn(msg, ctx) {
+        this.emit("warn", msg, ctx);
+    }
+    error(msg, ctx) {
+        this.emit("error", msg, ctx);
+    }
+}

package/dist/src/metrics.d.ts

@@ -0,0 +1,6 @@
+type Labels = Record<string, string | number | boolean>;
+export declare function incCounter(name: string, delta?: number, labels?: Labels): void;
+export declare function setGauge(name: string, value: number, labels?: Labels): void;
+export declare function observeHistogram(name: string, value: number, labels?: Labels, buckets?: number[]): void;
+export declare function renderPrometheusMetrics(): string;
+export {};

package/dist/src/metrics.js

@@ -0,0 +1,95 @@
+const metrics = new Map();
+const defaultBucketsMs = [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000];
+function normalizeLabels(labels) {
+    if (!labels)
+        return [];
+    return Object.entries(labels)
+        .map(([k, v]) => [k, String(v)])
+        .sort((a, b) => a[0].localeCompare(b[0]));
+}
+function labelKey(labels) {
+    return JSON.stringify(normalizeLabels(labels));
+}
+function renderLabelBlock(labelsKey) {
+    const labels = JSON.parse(labelsKey);
+    if (labels.length === 0)
+        return "";
+    const inner = labels.map(([k, v]) => `${k}="${v.replaceAll('"', '\\"')}"`).join(",");
+    return `{${inner}}`;
+}
+function ensureCounter(name) {
+    const existing = metrics.get(name);
+    if (existing && existing.type === "counter")
+        return existing;
+    const created = { type: "counter", values: new Map() };
+    metrics.set(name, created);
+    return created;
+}
+function ensureGauge(name) {
+    const existing = metrics.get(name);
+    if (existing && existing.type === "gauge")
+        return existing;
+    const created = { type: "gauge", values: new Map() };
+    metrics.set(name, created);
+    return created;
+}
+function ensureHistogram(name) {
+    const existing = metrics.get(name);
+    if (existing && existing.type === "histogram")
+        return existing;
+    const created = { type: "histogram", values: new Map() };
+    metrics.set(name, created);
+    return created;
+}
+export function incCounter(name, delta = 1, labels) {
+    const metric = ensureCounter(name);
+    const key = labelKey(labels);
+    metric.values.set(key, (metric.values.get(key) ?? 0) + delta);
+}
+export function setGauge(name, value, labels) {
+    const metric = ensureGauge(name);
+    metric.values.set(labelKey(labels), value);
+}
+export function observeHistogram(name, value, labels, buckets = defaultBucketsMs) {
+    const metric = ensureHistogram(name);
+    const key = labelKey(labels);
+    let series = metric.values.get(key);
+    if (!series) {
+        series = {
+            buckets: buckets.map((le) => ({ le, count: 0 })),
+            sum: 0,
+            count: 0
+        };
+        metric.values.set(key, series);
+    }
+    series.sum += value;
+    series.count += 1;
+    for (const bucket of series.buckets) {
+        if (value <= bucket.le)
+            bucket.count += 1;
+    }
+}
+export function renderPrometheusMetrics() {
+    const rows = [];
+    for (const [name, metric] of metrics.entries()) {
+        rows.push(`# TYPE ${name} ${metric.type}`);
+        if (metric.type === "counter" || metric.type === "gauge") {
+            for (const [labels, value] of metric.values.entries()) {
+                rows.push(`${name}${renderLabelBlock(labels)} ${value}`);
+            }
+            continue;
+        }
+        for (const [labels, series] of metric.values.entries()) {
+            const parsed = JSON.parse(labels);
+            for (const bucket of series.buckets) {
+                const bucketLabels = JSON.stringify([...parsed, ["le", String(bucket.le)]].sort((a, b) => a[0].localeCompare(b[0])));
+                rows.push(`${name}_bucket${renderLabelBlock(bucketLabels)} ${bucket.count}`);
+            }
+            const infLabels = JSON.stringify([...parsed, ["le", "+Inf"]].sort((a, b) => a[0].localeCompare(b[0])));
+            rows.push(`${name}_bucket${renderLabelBlock(infLabels)} ${series.count}`);
+            rows.push(`${name}_sum${renderLabelBlock(labels)} ${series.sum}`);
+            rows.push(`${name}_count${renderLabelBlock(labels)} ${series.count}`);
+        }
+    }
+    return `${rows.join("\n")}\n`;
+}

package/dist/src/nats.d.ts

@@ -0,0 +1,16 @@
+import { NatsConnection } from "nats";
+export declare function connectBus(url: string): Promise<NatsConnection>;
+export declare function closeBus(url: string): Promise<void>;
+export declare function encodeJson(value: unknown): Uint8Array;
+export declare function decodeJson(value: Uint8Array): unknown;
+export declare function kvPut(nc: NatsConnection, bucket: string, key: string, value: unknown): Promise<void>;
+export declare function kvGet<T>(nc: NatsConnection, bucket: string, key: string): Promise<T | null>;
+export declare function osPut(nc: NatsConnection, bucket: string, key: string, body: Uint8Array, options?: {
+    description?: string;
+    headers?: Record<string, string>;
+}): Promise<void>;
+export declare function publishSubject(nc: NatsConnection, subject: string, payload: Uint8Array, options?: {
+    durable?: boolean;
+    dedupeKey?: string;
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/src/nats.js

@@ -0,0 +1,129 @@
+import { connect, JSONCodec } from "nats";
+import { OrbitError } from "./errors.js";
+const jc = JSONCodec();
+const connectionCache = new Map();
+const kvViewCache = new WeakMap();
+const osViewCache = new WeakMap();
+export async function connectBus(url) {
+    const cached = connectionCache.get(url);
+    if (cached)
+        return cached;
+    const pending = connect({ servers: url })
+        .then((nc) => {
+        const remove = () => {
+            if (connectionCache.get(url) === pending)
+                connectionCache.delete(url);
+        };
+        nc.closed().then(remove).catch(remove);
+        return nc;
+    })
+        .catch((err) => {
+        if (connectionCache.get(url) === pending)
+            connectionCache.delete(url);
+        throw err;
+    });
+    connectionCache.set(url, pending);
+    return pending;
+}
+export async function closeBus(url) {
+    const pending = connectionCache.get(url);
+    if (!pending)
+        return;
+    connectionCache.delete(url);
+    const nc = await pending;
+    await nc.drain();
+}
+export function encodeJson(value) {
+    return jc.encode(value);
+}
+export function decodeJson(value) {
+    return jc.decode(value);
+}
+async function kvView(nc, bucket) {
+    const js = nc.jetstream();
+    let perConn = kvViewCache.get(nc);
+    if (!perConn) {
+        perConn = new Map();
+        kvViewCache.set(nc, perConn);
+    }
+    let kv = perConn.get(bucket);
+    if (!kv) {
+        kv = await js.views.kv(bucket, { history: 1 });
+        perConn.set(bucket, kv);
+    }
+    return kv;
+}
+async function osView(nc, bucket) {
+    const js = nc.jetstream();
+    let perConn = osViewCache.get(nc);
+    if (!perConn) {
+        perConn = new Map();
+        osViewCache.set(nc, perConn);
+    }
+    let os = perConn.get(bucket);
+    if (!os) {
+        os = await js.views.os(bucket);
+        perConn.set(bucket, os);
+    }
+    return os;
+}
+export async function kvPut(nc, bucket, key, value) {
+    const kv = await kvView(nc, bucket);
+    await kv.put(key, encodeJson(value));
+}
+export async function kvGet(nc, bucket, key) {
+    const kv = await kvView(nc, bucket);
+    const entry = await kv.get(key);
+    if (!entry)
+        return null;
+    return decodeJson(entry.value);
+}
+export async function osPut(nc, bucket, key, body, options) {
+    const os = await osView(nc, bucket);
+    try {
+        await os.put({
+            name: key,
+            data: body,
+            description: options?.description,
+            headers: options?.headers
+        });
+        return;
+    }
+    catch {
+        // Fallback signature for client variants.
+    }
+    try {
+        await os.put(key, body, options);
+        return;
+    }
+    catch {
+        // final fallback
+    }
+    await os.put({ name: key }, body);
+}
+export async function publishSubject(nc, subject, payload, options) {
+    if (!options?.durable) {
+        nc.publish(subject, payload);
+        return;
+    }
+    const js = nc.jetstream();
+    const publishPromise = js.publish(subject, payload, options.dedupeKey ? { msgID: options.dedupeKey } : undefined);
+    if (!options.timeoutMs || options.timeoutMs <= 0) {
+        await publishPromise;
+        return;
+    }
+    let timer;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new OrbitError("PUBLISH_TIMEOUT", `durable publish ack timed out after ${options.timeoutMs}ms for subject ${subject}`));
+        }, options.timeoutMs);
+        timer.unref?.();
+    });
+    try {
+        await Promise.race([publishPromise, timeoutPromise]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/src/orbit_actions.d.ts

@@ -0,0 +1,4 @@
+import { NatsConnection } from "nats";
+import { OrbitConfig } from "./types.js";
+import { OrbitApiAction } from "./api_contract.js";
+export declare function executeOrbitAction(config: OrbitConfig, nc: NatsConnection, action: OrbitApiAction, payload: Record<string, unknown>, actor: "api" | "agent"): Promise<unknown>;