macp-sdk-typescript 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,263 @@
+export interface Root {
+    uri: string;
+    name?: string;
+}
+export interface Envelope {
+    macpVersion: string;
+    mode: string;
+    messageType: string;
+    messageId: string;
+    sessionId: string;
+    sender: string;
+    timestampUnixMs: string;
+    payload: Buffer;
+}
+export interface MacpErrorShape {
+    code: string;
+    message: string;
+    sessionId?: string;
+    messageId?: string;
+    details?: Buffer;
+}
+export interface Ack {
+    ok?: boolean;
+    duplicate?: boolean;
+    messageId?: string;
+    sessionId?: string;
+    acceptedAtUnixMs?: string;
+    sessionState?: string;
+    error?: MacpErrorShape;
+}
+export interface ParticipantActivity {
+    participantId: string;
+    lastMessageAtUnixMs: string;
+    messageCount: number;
+}
+export interface SessionMetadata {
+    sessionId?: string;
+    mode?: string;
+    state?: string;
+    startedAtUnixMs?: string;
+    expiresAtUnixMs?: string;
+    modeVersion?: string;
+    configurationVersion?: string;
+    policyVersion?: string;
+    participants?: string[];
+    participantActivity?: ParticipantActivity[];
+    initiator?: string;
+}
+export interface ModeDescriptor {
+    mode: string;
+    modeVersion: string;
+    title?: string;
+    description?: string;
+    determinismClass?: string;
+    participantModel?: string;
+    messageTypes?: string[];
+    terminalMessageTypes?: string[];
+    schemaUris?: Record<string, string>;
+}
+export interface TransportEndpoint {
+    transport: string;
+    uri: string;
+    contentTypes?: string[];
+    metadata?: Record<string, string>;
+}
+export interface AgentManifest {
+    agentId?: string;
+    title?: string;
+    description?: string;
+    supportedModes?: string[];
+    inputContentTypes?: string[];
+    outputContentTypes?: string[];
+    metadata?: Record<string, string>;
+    transportEndpoints?: TransportEndpoint[];
+}
+export interface InitializeResult {
+    selectedProtocolVersion: string;
+    runtimeInfo?: {
+        name?: string;
+        title?: string;
+        version?: string;
+        description?: string;
+        websiteUrl?: string;
+    };
+    supportedModes?: string[];
+    instructions?: string;
+    capabilities?: Record<string, unknown>;
+}
+export interface SessionStartPayload {
+    intent: string;
+    participants: string[];
+    modeVersion: string;
+    configurationVersion: string;
+    policyVersion?: string;
+    ttlMs: number;
+    context?: Buffer;
+    roots?: Root[];
+}
+export interface CommitmentPayload {
+    commitmentId: string;
+    action: string;
+    authorityScope: string;
+    reason: string;
+    modeVersion: string;
+    policyVersion?: string;
+    configurationVersion: string;
+    outcomePositive?: boolean;
+}
+export interface SignalPayload {
+    signalType: string;
+    data?: Buffer;
+    confidence?: number;
+    correlationSessionId?: string;
+}
+export interface ProgressPayload {
+    progressToken: string;
+    progress: number;
+    total: number;
+    message?: string;
+    targetMessageId?: string;
+}
+export interface DecisionProposalPayload {
+    proposalId: string;
+    option: string;
+    rationale?: string;
+    supportingData?: Buffer;
+}
+export interface DecisionEvaluationPayload {
+    proposalId: string;
+    recommendation: string;
+    confidence: number;
+    reason?: string;
+}
+export interface DecisionObjectionPayload {
+    proposalId: string;
+    reason: string;
+    severity?: string;
+}
+export interface DecisionVotePayload {
+    proposalId: string;
+    vote: string;
+    reason?: string;
+}
+export interface ProposalModeProposalPayload {
+    proposalId: string;
+    title: string;
+    summary?: string;
+    details?: Buffer;
+    tags?: string[];
+}
+export interface CounterProposalPayload {
+    proposalId: string;
+    supersedesProposalId: string;
+    title: string;
+    summary?: string;
+    details?: Buffer;
+}
+export interface AcceptPayload {
+    proposalId: string;
+    reason?: string;
+}
+export interface RejectPayload {
+    proposalId: string;
+    terminal?: boolean;
+    reason?: string;
+}
+export interface WithdrawPayload {
+    proposalId: string;
+    reason?: string;
+}
+export interface TaskRequestPayload {
+    taskId: string;
+    title: string;
+    instructions: string;
+    requestedAssignee?: string;
+    input?: Buffer;
+    deadlineUnixMs?: number;
+}
+export interface TaskAcceptPayload {
+    taskId: string;
+    assignee: string;
+    reason?: string;
+}
+export interface TaskRejectPayload {
+    taskId: string;
+    assignee: string;
+    reason?: string;
+}
+export interface TaskUpdatePayload {
+    taskId: string;
+    status: string;
+    progress: number;
+    message?: string;
+    partialOutput?: Buffer;
+}
+export interface TaskCompletePayload {
+    taskId: string;
+    assignee: string;
+    output?: Buffer;
+    summary?: string;
+}
+export interface TaskFailPayload {
+    taskId: string;
+    assignee: string;
+    errorCode?: string;
+    reason?: string;
+    retryable?: boolean;
+}
+export interface HandoffOfferPayload {
+    handoffId: string;
+    targetParticipant: string;
+    scope?: string;
+    reason?: string;
+}
+export interface HandoffContextPayload {
+    handoffId: string;
+    contentType: string;
+    context?: Buffer;
+}
+export interface HandoffAcceptPayload {
+    handoffId: string;
+    acceptedBy: string;
+    reason?: string;
+}
+export interface HandoffDeclinePayload {
+    handoffId: string;
+    declinedBy: string;
+    reason?: string;
+}
+export interface ApprovalRequestPayload {
+    requestId: string;
+    action: string;
+    summary: string;
+    details?: Buffer;
+    requiredApprovals: number;
+}
+export interface ApprovePayload {
+    requestId: string;
+    reason?: string;
+}
+export interface QuorumRejectPayload {
+    requestId: string;
+    reason?: string;
+}
+export interface AbstainPayload {
+    requestId: string;
+    reason?: string;
+}
+export interface PolicyDescriptor {
+    policyId: string;
+    mode: string;
+    description: string;
+    rules: Buffer | Uint8Array;
+    schemaVersion: number;
+    registeredAtUnixMs?: number;
+}
+export interface RegistryChanged {
+    registry: string;
+    observedAtUnixMs: string;
+}
+export interface RootsChanged {
+    observedAtUnixMs: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/validation.d.ts

@@ -0,0 +1,17 @@
+export declare function validateSessionId(sid: string): void;
+export declare function validateVote(value: string): string;
+export declare function validateRecommendation(value: string): string;
+export declare function validateConfidence(value: number): void;
+export declare function validateSeverity(value: string): string;
+export declare function validateParticipantCount(count: number): void;
+export declare function validateSignalType(signalType: string, data?: Buffer | Uint8Array): void;
+export declare function validateTtlMs(ttlMs: number): void;
+export declare function validateParticipants(participants: string[]): void;
+export declare function validateRequiredField(fieldName: string, value: string): void;
+export declare function validateSessionStart(input: {
+    intent: string;
+    participants: string[];
+    ttlMs: number;
+    modeVersion: string;
+    configurationVersion: string;
+}): void;

package/dist/validation.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSessionId = validateSessionId;
+exports.validateVote = validateVote;
+exports.validateRecommendation = validateRecommendation;
+exports.validateConfidence = validateConfidence;
+exports.validateSeverity = validateSeverity;
+exports.validateParticipantCount = validateParticipantCount;
+exports.validateSignalType = validateSignalType;
+exports.validateTtlMs = validateTtlMs;
+exports.validateParticipants = validateParticipants;
+exports.validateRequiredField = validateRequiredField;
+exports.validateSessionStart = validateSessionStart;
+const errors_1 = require("./errors");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const BASE64URL_RE = /^[A-Za-z0-9_-]{22,}$/;
+function validateSessionId(sid) {
+    if (!UUID_RE.test(sid) && !BASE64URL_RE.test(sid)) {
+        throw new errors_1.MacpSessionError(`session_id must be UUID v4/v7 or base64url (22+ chars), got: ${sid}`);
+    }
+}
+const VALID_VOTES = new Set(['APPROVE', 'REJECT', 'ABSTAIN']);
+function validateVote(value) {
+    const normalized = value.toUpperCase();
+    if (!VALID_VOTES.has(normalized)) {
+        throw new errors_1.MacpSessionError(`invalid vote value '${value}': must be one of APPROVE, REJECT, ABSTAIN`);
+    }
+    return normalized;
+}
+const VALID_RECOMMENDATIONS = new Set(['APPROVE', 'REVIEW', 'BLOCK', 'REJECT']);
+function validateRecommendation(value) {
+    const normalized = value.toUpperCase();
+    if (!VALID_RECOMMENDATIONS.has(normalized)) {
+        throw new errors_1.MacpSessionError(`invalid recommendation '${value}': must be one of APPROVE, REVIEW, BLOCK, REJECT`);
+    }
+    return normalized;
+}
+function validateConfidence(value) {
+    if (value < 0.0 || value > 1.0) {
+        throw new errors_1.MacpSessionError(`confidence must be in [0.0, 1.0], got ${value}`);
+    }
+}
+const VALID_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
+function validateSeverity(value) {
+    const normalized = value.toLowerCase();
+    if (!VALID_SEVERITIES.has(normalized)) {
+        throw new errors_1.MacpSessionError(`invalid severity '${value}': must be one of critical, high, medium, low`);
+    }
+    return normalized;
+}
+const MAX_PARTICIPANTS = 1000;
+function validateParticipantCount(count) {
+    if (count > MAX_PARTICIPANTS) {
+        throw new errors_1.MacpSessionError(`Maximum ${MAX_PARTICIPANTS} participants per session`);
+    }
+}
+function validateSignalType(signalType, data) {
+    if (data && data.length > 0 && !signalType.trim()) {
+        throw new errors_1.MacpSessionError('signalType must be non-empty when data is present');
+    }
+}
+const MAX_TTL_MS = 86_400_000; // 24 hours
+function validateTtlMs(ttlMs) {
+    if (!Number.isFinite(ttlMs) || ttlMs < 1 || ttlMs > MAX_TTL_MS) {
+        throw new errors_1.MacpSessionError(`ttl_ms must be in [1, ${MAX_TTL_MS}], got ${ttlMs}`);
+    }
+}
+function validateParticipants(participants) {
+    if (!participants.length) {
+        throw new errors_1.MacpSessionError('participants must be non-empty');
+    }
+    const seen = new Set();
+    for (const p of participants) {
+        if (seen.has(p)) {
+            throw new errors_1.MacpSessionError(`duplicate participant: ${p}`);
+        }
+        seen.add(p);
+    }
+    validateParticipantCount(participants.length);
+}
+function validateRequiredField(fieldName, value) {
+    if (!value?.trim()) {
+        throw new errors_1.MacpSessionError(`${fieldName} must be non-empty`);
+    }
+}
+function validateSessionStart(input) {
+    validateRequiredField('intent', input.intent);
+    validateParticipants(input.participants);
+    validateTtlMs(input.ttlMs);
+    validateRequiredField('modeVersion', input.modeVersion);
+    validateRequiredField('configurationVersion', input.configurationVersion);
+}

package/dist/watchers.d.ts

@@ -0,0 +1,47 @@
+import type { AuthConfig } from './auth';
+import type { MacpClient } from './client';
+import type { Envelope, PolicyDescriptor, RegistryChanged, RootsChanged } from './types';
+export declare class ModeRegistryWatcher {
+    private readonly client;
+    private readonly auth?;
+    constructor(client: MacpClient, options?: {
+        auth?: AuthConfig;
+    });
+    changes(signal?: AbortSignal): AsyncGenerator<RegistryChanged, void, void>;
+    watch(handler: (change: RegistryChanged) => void | Promise<void>): Promise<void>;
+    nextChange(): Promise<RegistryChanged>;
+}
+export declare class RootsWatcher {
+    private readonly client;
+    private readonly auth?;
+    constructor(client: MacpClient, options?: {
+        auth?: AuthConfig;
+    });
+    changes(signal?: AbortSignal): AsyncGenerator<RootsChanged, void, void>;
+    watch(handler: (change: RootsChanged) => void | Promise<void>): Promise<void>;
+    nextChange(): Promise<RootsChanged>;
+}
+export declare class SignalWatcher {
+    private readonly client;
+    private readonly auth?;
+    constructor(client: MacpClient, options?: {
+        auth?: AuthConfig;
+    });
+    signals(signal?: AbortSignal): AsyncGenerator<Envelope, void, void>;
+    watch(handler: (envelope: Envelope) => void | Promise<void>): Promise<void>;
+    nextSignal(): Promise<Envelope>;
+}
+export interface PolicyChange {
+    descriptors: PolicyDescriptor[];
+    observedAtUnixMs: number;
+}
+export declare class PolicyWatcher {
+    private readonly client;
+    private readonly auth?;
+    constructor(client: MacpClient, options?: {
+        auth?: AuthConfig;
+    });
+    changes(signal?: AbortSignal): AsyncGenerator<PolicyChange, void, void>;
+    watch(handler: (change: PolicyChange) => void | Promise<void>): Promise<void>;
+    nextChange(): Promise<PolicyChange>;
+}

package/dist/watchers.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyWatcher = exports.SignalWatcher = exports.RootsWatcher = exports.ModeRegistryWatcher = void 0;
+function serverStreamToAsyncGenerator(stream) {
+    const queue = [];
+    let resolve = null;
+    stream.on('data', (data) => {
+        queue.push({ value: data });
+        if (resolve) {
+            resolve();
+            resolve = null;
+        }
+    });
+    stream.on('error', (error) => {
+        queue.push({ error });
+        if (resolve) {
+            resolve();
+            resolve = null;
+        }
+    });
+    stream.on('end', () => {
+        queue.push({ done: true });
+        if (resolve) {
+            resolve();
+            resolve = null;
+        }
+    });
+    return {
+        [Symbol.asyncIterator]() {
+            return this;
+        },
+        async next() {
+            while (true) {
+                const item = queue.shift();
+                if (item) {
+                    if ('done' in item)
+                        return { value: undefined, done: true };
+                    if ('error' in item)
+                        throw item.error;
+                    return { value: item.value, done: false };
+                }
+                await new Promise((r) => {
+                    resolve = r;
+                });
+            }
+        },
+        async return() {
+            stream.cancel();
+            return { value: undefined, done: true };
+        },
+        async throw(err) {
+            stream.cancel();
+            throw err;
+        },
+    };
+}
+class ModeRegistryWatcher {
+    client;
+    auth;
+    constructor(client, options) {
+        this.client = client;
+        this.auth = options?.auth;
+    }
+    async *changes(signal) {
+        const stream = this.client.watchModeRegistry(this.auth);
+        if (signal) {
+            signal.addEventListener('abort', () => stream.cancel(), { once: true });
+        }
+        yield* serverStreamToAsyncGenerator(stream);
+    }
+    async watch(handler) {
+        for await (const change of this.changes()) {
+            await handler(change);
+        }
+    }
+    async nextChange() {
+        const gen = this.changes();
+        const result = await gen.next();
+        await gen.return(undefined);
+        if (result.done)
+            throw new Error('stream ended before receiving a change');
+        return result.value;
+    }
+}
+exports.ModeRegistryWatcher = ModeRegistryWatcher;
+class RootsWatcher {
+    client;
+    auth;
+    constructor(client, options) {
+        this.client = client;
+        this.auth = options?.auth;
+    }
+    async *changes(signal) {
+        const stream = this.client.watchRoots(this.auth);
+        if (signal) {
+            signal.addEventListener('abort', () => stream.cancel(), { once: true });
+        }
+        yield* serverStreamToAsyncGenerator(stream);
+    }
+    async watch(handler) {
+        for await (const change of this.changes()) {
+            await handler(change);
+        }
+    }
+    async nextChange() {
+        const gen = this.changes();
+        const result = await gen.next();
+        await gen.return(undefined);
+        if (result.done)
+            throw new Error('stream ended before receiving a change');
+        return result.value;
+    }
+}
+exports.RootsWatcher = RootsWatcher;
+class SignalWatcher {
+    client;
+    auth;
+    constructor(client, options) {
+        this.client = client;
+        this.auth = options?.auth;
+    }
+    async *signals(signal) {
+        const stream = this.client.watchSignals(this.auth);
+        if (signal) {
+            signal.addEventListener('abort', () => stream.cancel(), { once: true });
+        }
+        const gen = serverStreamToAsyncGenerator(stream);
+        for await (const response of gen) {
+            if (response.envelope)
+                yield response.envelope;
+        }
+    }
+    async watch(handler) {
+        for await (const envelope of this.signals()) {
+            await handler(envelope);
+        }
+    }
+    async nextSignal() {
+        const gen = this.signals();
+        const result = await gen.next();
+        await gen.return(undefined);
+        if (result.done)
+            throw new Error('stream ended before receiving a signal');
+        return result.value;
+    }
+}
+exports.SignalWatcher = SignalWatcher;
+class PolicyWatcher {
+    client;
+    auth;
+    constructor(client, options) {
+        this.client = client;
+        this.auth = options?.auth;
+    }
+    async *changes(signal) {
+        const stream = this.client.watchPolicies(this.auth);
+        if (signal) {
+            signal.addEventListener('abort', () => stream.cancel(), { once: true });
+        }
+        yield* serverStreamToAsyncGenerator(stream);
+    }
+    async watch(handler) {
+        for await (const change of this.changes()) {
+            await handler(change);
+        }
+    }
+    async nextChange() {
+        const gen = this.changes();
+        const result = await gen.next();
+        await gen.return(undefined);
+        if (result.done)
+            throw new Error('stream ended before receiving a policy change');
+        return result.value;
+    }
+}
+exports.PolicyWatcher = PolicyWatcher;

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "macp-sdk-typescript",
+  "version": "0.2.0",
+  "description": "TypeScript SDK for the MACP Rust runtime",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts' --ignore-unknown",
+    "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.ts' --ignore-unknown",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --config vitest.config.ts",
+    "test:coverage": "vitest run --coverage --config vitest.config.ts",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "example:decision": "tsx examples/decision-smoke.ts",
+    "example:proposal": "tsx examples/proposal-smoke.ts",
+    "example:task": "tsx examples/task-smoke.ts",
+    "example:handoff": "tsx examples/handoff-smoke.ts",
+    "example:quorum": "tsx examples/quorum-smoke.ts",
+    "example:watch": "tsx examples/watch-smoke.ts",
+    "example:bearer": "tsx examples/bearer-smoke.ts",
+    "prepublishOnly": "npm run check && npm run lint && npm run format:check && npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "macp",
+    "multi-agent",
+    "coordination",
+    "grpc",
+    "protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/multiagentcoordinationprotocol/typescript-sdk.git"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "^1.14.3",
+    "@grpc/proto-loader": "^0.8.0",
+    "@multiagentcoordinationprotocol/proto": "^0.1.0",
+    "protobufjs": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.0.0"
+  }
+}