macp-sdk-typescript 0.2.0

package/dist/agent/transports.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpTransportAdapter = exports.GrpcTransportAdapter = void 0;
+function normalizeEnvelope(envelope, decodePayload, seq) {
+    const payload = decodePayload(envelope.mode, envelope.messageType, envelope.payload) ?? {};
+    return {
+        messageType: envelope.messageType,
+        sender: envelope.sender,
+        payload,
+        proposalId: payload.proposalId ?? payload.proposal_id,
+        raw: envelope,
+        seq,
+    };
+}
+class GrpcTransportAdapter {
+    client;
+    sessionId;
+    auth;
+    stream = null;
+    seq = 0;
+    constructor(client, sessionId, auth) {
+        this.client = client;
+        this.sessionId = sessionId;
+        this.auth = auth;
+    }
+    async *start() {
+        this.stream = this.client.openStream({ auth: this.auth });
+        for await (const envelope of this.stream.responses()) {
+            if (envelope.sessionId !== this.sessionId)
+                continue;
+            yield normalizeEnvelope(envelope, (mode, mt, p) => this.client.protoRegistry.decodeKnownPayload(mode, mt, p), this.seq++);
+        }
+    }
+    async stop() {
+        if (this.stream) {
+            this.stream.close();
+            this.stream = null;
+        }
+    }
+}
+exports.GrpcTransportAdapter = GrpcTransportAdapter;
+class HttpTransportAdapter {
+    config;
+    stopped = false;
+    seq = 0;
+    lastSeq = -1;
+    constructor(config) {
+        this.config = config;
+    }
+    async *start() {
+        while (!this.stopped) {
+            try {
+                const headers = { 'Content-Type': 'application/json' };
+                if (this.config.authToken) {
+                    headers['Authorization'] = `Bearer ${this.config.authToken}`;
+                }
+                const url = `${this.config.baseUrl}/sessions/${this.config.sessionId}/events?after=${this.lastSeq}`;
+                const response = await fetch(url, { headers });
+                if (!response.ok) {
+                    await this.sleep(this.config.pollIntervalMs);
+                    continue;
+                }
+                const body = await response.json();
+                // Accept both Python format (JSON array of items) and
+                // TypeScript format ({ events: [{ envelope, seq }] }).
+                if (Array.isArray(body)) {
+                    // Python-style: plain array of envelope-like objects
+                    for (const item of body) {
+                        const itemSeq = item.seq ?? this.lastSeq + 1;
+                        if (itemSeq > this.lastSeq) {
+                            this.lastSeq = itemSeq;
+                        }
+                        yield {
+                            messageType: item.message_type ?? item.messageType ?? '',
+                            sender: item.sender ?? '',
+                            payload: typeof item.payload === 'object' && item.payload !== null
+                                ? item.payload
+                                : this.tryParsePayload(item.payload),
+                            proposalId: item.proposal_id ?? item.proposalId,
+                            raw: item,
+                            seq: this.seq++,
+                        };
+                    }
+                }
+                else {
+                    // TypeScript-style: { events: [{ envelope, seq }] }
+                    const wrapped = body;
+                    const events = wrapped.events ?? [];
+                    for (const event of events) {
+                        if (event.seq > this.lastSeq) {
+                            this.lastSeq = event.seq;
+                        }
+                        yield {
+                            messageType: event.envelope.messageType,
+                            sender: event.envelope.sender,
+                            payload: this.tryParsePayload(event.envelope.payload),
+                            raw: event.envelope,
+                            seq: this.seq++,
+                        };
+                    }
+                }
+            }
+            catch {
+                // Ignore errors, retry after interval
+            }
+            await this.sleep(this.config.pollIntervalMs);
+        }
+    }
+    async stop() {
+        this.stopped = true;
+    }
+    tryParsePayload(payload) {
+        try {
+            const text = typeof payload === 'string' ? payload : Buffer.from(payload).toString('utf8');
+            return JSON.parse(text);
+        }
+        catch {
+            return {};
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.HttpTransportAdapter = HttpTransportAdapter;

package/dist/agent/types.d.ts

@@ -0,0 +1,72 @@
+import type { Envelope } from '../types';
+export interface IncomingMessage {
+    messageType: string;
+    sender: string;
+    payload: Record<string, unknown>;
+    proposalId?: string;
+    raw: Envelope;
+    seq?: number;
+}
+export interface SessionInfo {
+    sessionId: string;
+    mode: string;
+    participants: string[];
+    modeVersion?: string;
+    configurationVersion?: string;
+    policyVersion?: string;
+}
+export interface SessionActions {
+    evaluate?(input: {
+        proposalId: string;
+        recommendation: string;
+        confidence: number;
+        reason?: string;
+    }): Promise<void>;
+    vote?(input: {
+        proposalId: string;
+        vote: string;
+        reason?: string;
+    }): Promise<void>;
+    raiseObjection?(input: {
+        proposalId: string;
+        reason: string;
+        severity?: string;
+    }): Promise<void>;
+    propose?(input: {
+        proposalId: string;
+        option: string;
+        rationale?: string;
+        supportingData?: Buffer;
+    }): Promise<void>;
+    commit?(input: {
+        action: string;
+        authorityScope: string;
+        reason: string;
+        commitmentId?: string;
+        outcomePositive?: boolean;
+    }): Promise<void>;
+    send?(messageType: string, payload: Record<string, unknown>): Promise<void>;
+}
+export interface HandlerContext {
+    participant: ParticipantLike;
+    projection: ProjectionLike;
+    actions: SessionActions;
+    session: SessionInfo;
+    log: (msg: string, details?: Record<string, unknown>) => void;
+}
+export interface ParticipantLike {
+    readonly participantId: string;
+    readonly sessionId: string;
+    readonly mode: string;
+}
+export interface ProjectionLike {
+    readonly phase: string;
+    readonly transcript: Envelope[];
+}
+export type MessageHandler = (event: IncomingMessage, ctx: HandlerContext) => void | Promise<void>;
+export type TerminalHandler = (result: TerminalResult) => void | Promise<void>;
+export type PhaseChangeHandler = (newPhase: string, ctx: HandlerContext) => void | Promise<void>;
+export interface TerminalResult {
+    state: string;
+    commitment?: Record<string, unknown>;
+}

package/dist/agent/types.js

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

package/dist/auth.d.ts

@@ -0,0 +1,52 @@
+import * as grpc from '@grpc/grpc-js';
+export interface AuthConfig {
+    bearerToken?: string;
+    agentId?: string;
+    senderHint?: string;
+    /**
+     * The authenticated sender this credential represents. When present, the SDK
+     * refuses to emit an envelope whose `sender` differs from this value
+     * (RFC-MACP-0004 §4). Leave undefined for legacy/dev flows that want to
+     * retain the pre-0.2 permissive behavior.
+     */
+    expectedSender?: string;
+}
+/**
+ * Optional second argument to {@link Auth.bearer}. Accepts either a bare
+ * `senderHint` string (legacy) or a structured object that can also declare
+ * the authenticated identity via `expectedSender`.
+ */
+export type BearerAuthOptions = string | {
+    expectedSender?: string;
+    senderHint?: string;
+};
+export declare const Auth: {
+    /**
+     * Dev-mode agent identity. Uses the `x-macp-agent-id` header — only accepted
+     * by runtimes started with `MACP_ALLOW_DEV_SENDER_HEADER=1`. Not for
+     * production. Does not set {@link AuthConfig.expectedSender}; dev flows stay
+     * permissive so tests can reuse a single credential across senders.
+     */
+    devAgent(agentId: string): AuthConfig;
+    /**
+     * Production bearer-token credential. Pass `{ expectedSender }` to have the
+     * SDK refuse to emit envelopes whose `sender` differs from the authenticated
+     * identity (RFC-MACP-0004 §4).
+     *
+     * ```ts
+     * Auth.bearer('tok')                               // legacy; no identity guard
+     * Auth.bearer('tok', 'alice')                      // legacy; alice is senderHint only
+     * Auth.bearer('tok', { expectedSender: 'alice' })  // strict; SDK enforces sender=='alice'
+     * ```
+     */
+    bearer(token: string, options?: BearerAuthOptions): AuthConfig;
+};
+export declare function validateAuth(auth: AuthConfig): void;
+export declare function authSender(auth?: AuthConfig): string | undefined;
+/**
+ * Throw {@link MacpIdentityMismatchError} when a caller-supplied `sender`
+ * conflicts with `auth.expectedSender`. Silent when either is undefined, so
+ * dev credentials and legacy bearer usage retain pre-0.2 behavior.
+ */
+export declare function assertSenderMatchesIdentity(auth: AuthConfig | undefined, sender: string | undefined): void;
+export declare function metadataFromAuth(auth: AuthConfig): grpc.Metadata;

package/dist/auth.js

@@ -0,0 +1,112 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Auth = void 0;
+exports.validateAuth = validateAuth;
+exports.authSender = authSender;
+exports.assertSenderMatchesIdentity = assertSenderMatchesIdentity;
+exports.metadataFromAuth = metadataFromAuth;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const errors_1 = require("./errors");
+exports.Auth = {
+    /**
+     * Dev-mode agent identity. Uses the `x-macp-agent-id` header — only accepted
+     * by runtimes started with `MACP_ALLOW_DEV_SENDER_HEADER=1`. Not for
+     * production. Does not set {@link AuthConfig.expectedSender}; dev flows stay
+     * permissive so tests can reuse a single credential across senders.
+     */
+    devAgent(agentId) {
+        return { agentId, senderHint: agentId };
+    },
+    /**
+     * Production bearer-token credential. Pass `{ expectedSender }` to have the
+     * SDK refuse to emit envelopes whose `sender` differs from the authenticated
+     * identity (RFC-MACP-0004 §4).
+     *
+     * ```ts
+     * Auth.bearer('tok')                               // legacy; no identity guard
+     * Auth.bearer('tok', 'alice')                      // legacy; alice is senderHint only
+     * Auth.bearer('tok', { expectedSender: 'alice' })  // strict; SDK enforces sender=='alice'
+     * ```
+     */
+    bearer(token, options) {
+        if (options === undefined)
+            return { bearerToken: token };
+        if (typeof options === 'string')
+            return { bearerToken: token, senderHint: options };
+        const { expectedSender, senderHint } = options;
+        return {
+            bearerToken: token,
+            expectedSender,
+            senderHint: senderHint ?? expectedSender,
+        };
+    },
+};
+function validateAuth(auth) {
+    if (!auth.bearerToken && !auth.agentId) {
+        throw new Error('either bearerToken or agentId is required');
+    }
+    if (auth.bearerToken && auth.agentId) {
+        throw new Error('choose either bearerToken or agentId, not both');
+    }
+}
+function authSender(auth) {
+    if (!auth)
+        return undefined;
+    return auth.expectedSender ?? auth.senderHint ?? auth.agentId;
+}
+/**
+ * Throw {@link MacpIdentityMismatchError} when a caller-supplied `sender`
+ * conflicts with `auth.expectedSender`. Silent when either is undefined, so
+ * dev credentials and legacy bearer usage retain pre-0.2 behavior.
+ */
+function assertSenderMatchesIdentity(auth, sender) {
+    if (!auth?.expectedSender)
+        return;
+    if (sender === undefined)
+        return;
+    if (sender !== auth.expectedSender) {
+        throw new errors_1.MacpIdentityMismatchError(auth.expectedSender, sender);
+    }
+}
+function metadataFromAuth(auth) {
+    validateAuth(auth);
+    const metadata = new grpc.Metadata();
+    if (auth.bearerToken)
+        metadata.set('authorization', `Bearer ${auth.bearerToken}`);
+    if (auth.agentId)
+        metadata.set('x-macp-agent-id', auth.agentId);
+    return metadata;
+}

package/dist/client.d.ts

@@ -0,0 +1,171 @@
+import * as grpc from '@grpc/grpc-js';
+import { type AuthConfig } from './auth';
+import { ProtoRegistry } from './proto-registry';
+import type { Ack, AgentManifest, Envelope, InitializeResult, ModeDescriptor, PolicyDescriptor, SessionMetadata, Root } from './types';
+interface MacpClientOptions {
+    address: string;
+    /**
+     * Use TLS credentials. Defaults to `true` per RFC-MACP-0006 §3. Pass
+     * `secure: false` together with {@link MacpClientOptions.allowInsecure}
+     * `true` for local development against an insecure runtime.
+     */
+    secure?: boolean;
+    /**
+     * Opt out of the secure-by-default guard. Must be set to `true` whenever
+     * `secure` is `false`; otherwise the constructor throws. Intentionally
+     * verbose so agents never ship to production with TLS off by accident.
+     */
+    allowInsecure?: boolean;
+    auth?: AuthConfig;
+    rootCertificates?: Buffer;
+    defaultDeadlineMs?: number;
+    clientName?: string;
+    clientVersion?: string;
+    protoDir?: string;
+}
+export type InlineErrorCallback = (error: {
+    code?: string;
+    message?: string;
+}) => void;
+export declare class MacpStream {
+    private readonly call;
+    private readonly queue;
+    private closed;
+    private readonly inlineErrorCallbacks;
+    constructor(call: grpc.ClientDuplexStream<any, any>);
+    onInlineError(callback: InlineErrorCallback): void;
+    send(envelope: Envelope): Promise<void>;
+    responses(): AsyncGenerator<Envelope, void, void>;
+    close(): void;
+}
+export declare class MacpClient {
+    readonly auth?: AuthConfig;
+    readonly protoRegistry: ProtoRegistry;
+    private readonly client;
+    private readonly secure;
+    private readonly defaultDeadlineMs?;
+    private readonly clientName;
+    private readonly clientVersion;
+    constructor(options: MacpClientOptions);
+    private requireAuth;
+    private metadata;
+    private deadline;
+    private unary;
+    initialize(deadlineMs?: number): Promise<InitializeResult>;
+    send(envelope: Envelope, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+        raiseOnNack?: boolean;
+    }): Promise<Ack>;
+    getSession(sessionId: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<{
+        metadata: SessionMetadata;
+    }>;
+    cancelSession(sessionId: string, reason: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+        raiseOnNack?: boolean;
+        cancelledBy?: string;
+    }): Promise<Ack>;
+    getManifest(agentId?: string, deadlineMs?: number): Promise<{
+        manifest: AgentManifest;
+    }>;
+    listModes(deadlineMs?: number): Promise<{
+        modes: ModeDescriptor[];
+    }>;
+    listExtModes(deadlineMs?: number): Promise<{
+        modes: ModeDescriptor[];
+    }>;
+    listRoots(deadlineMs?: number): Promise<{
+        roots: Root[];
+    }>;
+    registerExtMode(descriptor: ModeDescriptor, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    unregisterExtMode(mode: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    promoteMode(mode: string, promotedModeName?: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+        mode?: string;
+    }>;
+    registerPolicy(descriptor: PolicyDescriptor, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    unregisterPolicy(policyId: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    getPolicy(policyId: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<PolicyDescriptor>;
+    listPolicies(mode?: string, options?: {
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<PolicyDescriptor[]>;
+    watchPolicies(auth?: AuthConfig): grpc.ClientReadableStream<any>;
+    /** @deprecated Use {@link watchPolicies}. Scheduled for removal in 0.4.0. */
+    _watchPolicies(auth?: AuthConfig): grpc.ClientReadableStream<any>;
+    openStream(options?: {
+        auth?: AuthConfig;
+    }): MacpStream;
+    watchModeRegistry(auth?: AuthConfig): grpc.ClientReadableStream<any>;
+    watchRoots(auth?: AuthConfig): grpc.ClientReadableStream<any>;
+    watchSignals(auth?: AuthConfig): grpc.ClientReadableStream<any>;
+    /**
+     * @deprecated Use {@link watchModeRegistry}, {@link watchRoots},
+     * {@link watchSignals}. Scheduled for removal in 0.4.0 — the underscored
+     * aliases were kept while `src/watchers.ts` migrated.
+     */
+    _watchModeRegistry(auth?: AuthConfig): grpc.ClientReadableStream<any>;
+    /** @deprecated Use {@link watchRoots}. Scheduled for removal in 0.4.0. */
+    _watchRoots(auth?: AuthConfig): grpc.ClientReadableStream<any>;
+    /** @deprecated Use {@link watchSignals}. Scheduled for removal in 0.4.0. */
+    _watchSignals(auth?: AuthConfig): grpc.ClientReadableStream<any>;
+    sendSignal(options: {
+        signalType: string;
+        data?: Buffer;
+        confidence?: number;
+        correlationSessionId?: string;
+        sender?: string;
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<Ack>;
+    sendProgress(options: {
+        sessionId?: string;
+        mode?: string;
+        progressToken: string;
+        progress: number;
+        total: number;
+        message?: string;
+        targetMessageId?: string;
+        sender?: string;
+        auth?: AuthConfig;
+        deadlineMs?: number;
+    }): Promise<Ack>;
+    senderHint(auth?: AuthConfig): string | undefined;
+    close(): void;
+}
+export {};