macp-sdk-typescript 0.2.0

package/dist/agent/index.js

@@ -0,0 +1,25 @@
+"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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpTransportAdapter = exports.GrpcTransportAdapter = void 0;
+__exportStar(require("./types"), exports);
+__exportStar(require("./dispatcher"), exports);
+__exportStar(require("./participant"), exports);
+__exportStar(require("./strategies"), exports);
+__exportStar(require("./runner"), exports);
+var transports_1 = require("./transports");
+Object.defineProperty(exports, "GrpcTransportAdapter", { enumerable: true, get: function () { return transports_1.GrpcTransportAdapter; } });
+Object.defineProperty(exports, "HttpTransportAdapter", { enumerable: true, get: function () { return transports_1.HttpTransportAdapter; } });

package/dist/agent/participant.d.ts

@@ -0,0 +1,38 @@
+import type { AuthConfig } from '../auth';
+import type { MacpClient } from '../client';
+import { type TransportAdapter } from './transports';
+import type { MessageHandler, PhaseChangeHandler, ProjectionLike, SessionActions, TerminalHandler } from './types';
+export interface ParticipantConfig {
+    participantId: string;
+    sessionId: string;
+    mode: string;
+    client: MacpClient;
+    auth?: AuthConfig;
+    participants?: string[];
+    modeVersion?: string;
+    configurationVersion?: string;
+    policyVersion?: string;
+    transport?: TransportAdapter;
+}
+export declare class Participant {
+    readonly participantId: string;
+    readonly sessionId: string;
+    readonly mode: string;
+    readonly client: MacpClient;
+    readonly auth?: AuthConfig;
+    readonly projection: ProjectionLike;
+    readonly actions: SessionActions;
+    private readonly dispatcher;
+    private readonly session;
+    private readonly transport;
+    private running;
+    private lastPhase;
+    constructor(config: ParticipantConfig);
+    private createModeSession;
+    private buildActions;
+    on(messageType: string, handler: MessageHandler): Participant;
+    onPhaseChange(phase: string, handler: PhaseChangeHandler): Participant;
+    onTerminal(handler: TerminalHandler): Participant;
+    run(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/agent/participant.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Participant = void 0;
+const constants_1 = require("../constants");
+const decision_1 = require("../decision");
+const handoff_1 = require("../handoff");
+const decision_2 = require("../projections/decision");
+const proposal_1 = require("../proposal");
+const quorum_1 = require("../quorum");
+const task_1 = require("../task");
+const dispatcher_1 = require("./dispatcher");
+const transports_1 = require("./transports");
+class Participant {
+    participantId;
+    sessionId;
+    mode;
+    client;
+    auth;
+    projection;
+    actions;
+    dispatcher;
+    session;
+    transport;
+    running = false;
+    lastPhase;
+    constructor(config) {
+        this.participantId = config.participantId;
+        this.sessionId = config.sessionId;
+        this.mode = config.mode;
+        this.client = config.client;
+        this.auth = config.auth;
+        this.dispatcher = new dispatcher_1.Dispatcher();
+        const sessionOpts = {
+            sessionId: config.sessionId,
+            modeVersion: config.modeVersion,
+            configurationVersion: config.configurationVersion,
+            policyVersion: config.policyVersion,
+            auth: config.auth,
+        };
+        const { session, projection } = this.createModeSession(config.mode, config.client, sessionOpts);
+        this.session = session;
+        this.projection = projection;
+        this.lastPhase = projection.phase;
+        this.actions = this.buildActions();
+        this.transport = config.transport ?? new transports_1.GrpcTransportAdapter(config.client, config.sessionId, config.auth);
+    }
+    createModeSession(mode, client, opts) {
+        switch (mode) {
+            case constants_1.MODE_DECISION: {
+                const s = new decision_1.DecisionSession(client, opts);
+                return { session: s, projection: s.projection };
+            }
+            case constants_1.MODE_PROPOSAL: {
+                const s = new proposal_1.ProposalSession(client, opts);
+                return { session: s, projection: s.projection };
+            }
+            case constants_1.MODE_TASK: {
+                const s = new task_1.TaskSession(client, opts);
+                return { session: s, projection: s.projection };
+            }
+            case constants_1.MODE_HANDOFF: {
+                const s = new handoff_1.HandoffSession(client, opts);
+                return { session: s, projection: s.projection };
+            }
+            case constants_1.MODE_QUORUM: {
+                const s = new quorum_1.QuorumSession(client, opts);
+                return { session: s, projection: s.projection };
+            }
+            default: {
+                const fallback = new decision_2.DecisionProjection();
+                return { session: null, projection: fallback };
+            }
+        }
+    }
+    buildActions() {
+        const participantId = this.participantId;
+        const actions = {};
+        if (this.session instanceof decision_1.DecisionSession) {
+            const ds = this.session;
+            actions.evaluate = async (input) => {
+                await ds.evaluate({ ...input, sender: participantId });
+            };
+            actions.vote = async (input) => {
+                await ds.vote({ ...input, sender: participantId });
+            };
+            actions.raiseObjection = async (input) => {
+                await ds.raiseObjection({ ...input, sender: participantId });
+            };
+            actions.propose = async (input) => {
+                await ds.propose({ ...input, sender: participantId });
+            };
+            actions.commit = async (input) => {
+                await ds.commit({ ...input, sender: participantId });
+            };
+        }
+        if (this.session instanceof proposal_1.ProposalSession) {
+            const ps = this.session;
+            actions.propose = async (input) => {
+                await ps.propose({
+                    proposalId: input.proposalId,
+                    title: input.option,
+                    summary: input.rationale,
+                    sender: participantId,
+                });
+            };
+            actions.commit = async (input) => {
+                await ps.commit({ ...input, sender: participantId });
+            };
+        }
+        if (this.session instanceof task_1.TaskSession) {
+            const ts = this.session;
+            actions.commit = async (input) => {
+                await ts.commit({ ...input, sender: participantId });
+            };
+        }
+        if (this.session instanceof handoff_1.HandoffSession) {
+            const hs = this.session;
+            actions.commit = async (input) => {
+                await hs.commit({ ...input, sender: participantId });
+            };
+        }
+        if (this.session instanceof quorum_1.QuorumSession) {
+            const qs = this.session;
+            actions.commit = async (input) => {
+                await qs.commit({ ...input, sender: participantId });
+            };
+        }
+        const mode = this.mode;
+        const sessionId = this.sessionId;
+        const client = this.client;
+        const auth = this.auth;
+        actions.send = async (messageType, payload) => {
+            const { buildEnvelope } = await import('../envelope.js');
+            const envelope = buildEnvelope({
+                mode,
+                messageType,
+                sessionId,
+                sender: participantId,
+                payload: client.protoRegistry.encodeKnownPayload(mode, messageType, payload),
+            });
+            await client.send(envelope, { auth });
+        };
+        return actions;
+    }
+    on(messageType, handler) {
+        this.dispatcher.on(messageType, handler);
+        return this;
+    }
+    onPhaseChange(phase, handler) {
+        this.dispatcher.onPhaseChange(phase, handler);
+        return this;
+    }
+    onTerminal(handler) {
+        this.dispatcher.onTerminal(handler);
+        return this;
+    }
+    async run() {
+        if (this.running)
+            return;
+        this.running = true;
+        const sessionInfo = {
+            sessionId: this.sessionId,
+            mode: this.mode,
+            participants: [],
+            policyVersion: undefined,
+        };
+        try {
+            for await (const message of this.transport.start()) {
+                if (!this.running)
+                    break;
+                const ctx = {
+                    participant: this,
+                    projection: this.projection,
+                    actions: this.actions,
+                    session: sessionInfo,
+                    log: (msg, details) => {
+                        // eslint-disable-next-line no-console
+                        console.log(`[${this.participantId}] ${msg}`, details ?? '');
+                    },
+                };
+                // Apply envelope to projection if we have a mode session
+                if (this.session && message.raw) {
+                    const applyMethod = this.session
+                        .projection.applyEnvelope;
+                    if (typeof applyMethod === 'function') {
+                        applyMethod.call(this.session.projection, message.raw, this.client.protoRegistry);
+                    }
+                }
+                // Dispatch message
+                await this.dispatcher.dispatch(message, ctx);
+                // Check for phase change
+                const currentPhase = this.projection.phase;
+                if (currentPhase !== this.lastPhase) {
+                    this.lastPhase = currentPhase;
+                    await this.dispatcher.dispatchPhaseChange(currentPhase, ctx);
+                    // Check for terminal state
+                    if (currentPhase === 'Committed' ||
+                        currentPhase === 'Accepted' ||
+                        currentPhase === 'Declined' ||
+                        currentPhase === 'Cancelled' ||
+                        currentPhase === 'TerminalRejected') {
+                        const terminalResult = {
+                            state: currentPhase,
+                            commitment: this.projection.commitment,
+                        };
+                        await this.dispatcher.dispatchTerminal(terminalResult);
+                        break;
+                    }
+                }
+            }
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    async stop() {
+        this.running = false;
+        await this.transport.stop();
+    }
+}
+exports.Participant = Participant;

package/dist/agent/runner.d.ts

@@ -0,0 +1,18 @@
+import { Participant } from './participant';
+export interface BootstrapPayload {
+    session_id: string;
+    participant_id: string;
+    mode: string;
+    mode_version?: string;
+    configuration_version?: string;
+    policy_version?: string;
+    runtime_address?: string;
+    runtime_url?: string;
+    auth_token?: string;
+    agent_id?: string;
+    secure?: boolean;
+    /** Mirror of {@link MacpClientOptions.allowInsecure}; required when `secure` is false. */
+    allow_insecure?: boolean;
+    participants?: string[];
+}
+export declare function fromBootstrap(bootstrapPath?: string): Participant;

package/dist/agent/runner.js

@@ -0,0 +1,84 @@
+"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.fromBootstrap = fromBootstrap;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const auth_1 = require("../auth");
+const client_1 = require("../client");
+const constants_1 = require("../constants");
+const participant_1 = require("./participant");
+function fromBootstrap(bootstrapPath) {
+    const resolvedPath = bootstrapPath ?? process.env.MACP_BOOTSTRAP_FILE;
+    if (!resolvedPath) {
+        throw new Error('No bootstrap path provided. Either pass a path argument or set the MACP_BOOTSTRAP_FILE environment variable.');
+    }
+    const absolutePath = path.isAbsolute(resolvedPath) ? resolvedPath : path.resolve(process.cwd(), resolvedPath);
+    if (!fs.existsSync(absolutePath)) {
+        throw new Error(`Bootstrap file not found: ${absolutePath}`);
+    }
+    const raw = fs.readFileSync(absolutePath, 'utf8');
+    const payload = JSON.parse(raw);
+    if (!payload.session_id)
+        throw new Error('Bootstrap payload missing session_id');
+    if (!payload.participant_id)
+        throw new Error('Bootstrap payload missing participant_id');
+    if (!payload.mode)
+        throw new Error('Bootstrap payload missing mode');
+    const runtimeAddress = payload.runtime_address ?? payload.runtime_url ?? '';
+    if (!runtimeAddress)
+        throw new Error('Bootstrap payload missing runtime_address / runtime_url');
+    const auth = payload.auth_token
+        ? auth_1.Auth.bearer(payload.auth_token, { expectedSender: payload.participant_id })
+        : auth_1.Auth.devAgent(payload.agent_id ?? payload.participant_id);
+    const client = new client_1.MacpClient({
+        address: runtimeAddress,
+        secure: payload.secure,
+        allowInsecure: payload.allow_insecure,
+        auth,
+    });
+    const config = {
+        participantId: payload.participant_id,
+        sessionId: payload.session_id,
+        mode: payload.mode,
+        client,
+        auth,
+        participants: payload.participants ?? [],
+        modeVersion: payload.mode_version,
+        configurationVersion: payload.configuration_version,
+        policyVersion: payload.policy_version ?? constants_1.DEFAULT_POLICY_VERSION,
+    };
+    return new participant_1.Participant(config);
+}

package/dist/agent/strategies.d.ts

@@ -0,0 +1,40 @@
+import type { DecisionProjection } from '../projections/decision';
+import type { MessageHandler, SessionInfo } from './types';
+export interface EvaluationResult {
+    recommendation: string;
+    confidence: number;
+    reason: string;
+}
+export interface EvaluationStrategy {
+    evaluate(proposal: Record<string, unknown>, context: SessionInfo): Promise<EvaluationResult>;
+}
+export declare function evaluationHandler(strategy: EvaluationStrategy): MessageHandler;
+export declare function functionEvaluator(fn: (proposal: Record<string, unknown>, context: SessionInfo) => Promise<EvaluationResult>): EvaluationStrategy;
+export interface VoteResult {
+    vote: string;
+    reason: string;
+}
+export interface VotingStrategy {
+    shouldVote(projection: DecisionProjection): boolean;
+    decideVote(projection: DecisionProjection): Promise<VoteResult>;
+}
+export declare function votingHandler(strategy: VotingStrategy): MessageHandler;
+export declare function majorityVoter(options?: {
+    positiveThreshold?: number;
+}): VotingStrategy;
+export interface CommitmentResult {
+    action: string;
+    authorityScope: string;
+    reason: string;
+    outcomePositive?: boolean;
+}
+export interface CommitmentStrategy {
+    shouldCommit(projection: DecisionProjection): boolean;
+    decideCommitment(projection: DecisionProjection): Promise<CommitmentResult>;
+}
+export declare function commitmentHandler(strategy: CommitmentStrategy): MessageHandler;
+export declare function majorityCommitter(options?: {
+    quorumSize?: number;
+    action?: string;
+    authorityScope?: string;
+}): CommitmentStrategy;

package/dist/agent/strategies.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluationHandler = evaluationHandler;
+exports.functionEvaluator = functionEvaluator;
+exports.votingHandler = votingHandler;
+exports.majorityVoter = majorityVoter;
+exports.commitmentHandler = commitmentHandler;
+exports.majorityCommitter = majorityCommitter;
+const envelope_1 = require("../envelope");
+function evaluationHandler(strategy) {
+    return async (event, ctx) => {
+        if (event.messageType !== 'Proposal')
+            return;
+        const result = await strategy.evaluate(event.payload, ctx.session);
+        if (ctx.actions.evaluate) {
+            await ctx.actions.evaluate({
+                proposalId: event.proposalId ?? event.payload.proposalId ?? event.payload.proposal_id,
+                recommendation: result.recommendation,
+                confidence: result.confidence,
+                reason: result.reason,
+            });
+        }
+    };
+}
+function functionEvaluator(fn) {
+    return { evaluate: fn };
+}
+function votingHandler(strategy) {
+    return async (event, ctx) => {
+        if (event.messageType !== 'Evaluation')
+            return;
+        const projection = ctx.projection;
+        if (!strategy.shouldVote(projection))
+            return;
+        const result = await strategy.decideVote(projection);
+        if (ctx.actions.vote) {
+            const proposalId = event.proposalId ?? event.payload.proposalId ?? event.payload.proposal_id;
+            await ctx.actions.vote({
+                proposalId,
+                vote: result.vote,
+                reason: result.reason,
+            });
+        }
+    };
+}
+function majorityVoter(options) {
+    const threshold = options?.positiveThreshold ?? 0.5;
+    return {
+        shouldVote(projection) {
+            return projection.evaluations.length > 0;
+        },
+        async decideVote(projection) {
+            const positive = projection.evaluations.filter((e) => ['approve', 'accept', 'yes'].includes(e.recommendation.toLowerCase()));
+            const ratio = projection.evaluations.length > 0 ? positive.length / projection.evaluations.length : 0;
+            if (ratio >= threshold) {
+                return { vote: 'APPROVE', reason: `${positive.length}/${projection.evaluations.length} evaluations positive` };
+            }
+            return {
+                vote: 'REJECT',
+                reason: `Only ${positive.length}/${projection.evaluations.length} evaluations positive`,
+            };
+        },
+    };
+}
+function commitmentHandler(strategy) {
+    return async (event, ctx) => {
+        if (event.messageType !== 'Vote')
+            return;
+        const projection = ctx.projection;
+        if (!strategy.shouldCommit(projection))
+            return;
+        const result = await strategy.decideCommitment(projection);
+        if (ctx.actions.commit) {
+            await ctx.actions.commit({
+                action: result.action,
+                authorityScope: result.authorityScope,
+                reason: result.reason,
+                outcomePositive: result.outcomePositive ?? (0, envelope_1.inferOutcomePositive)(result.action),
+            });
+        }
+    };
+}
+function majorityCommitter(options) {
+    const quorum = options?.quorumSize ?? 1;
+    const action = options?.action ?? 'commit';
+    const authorityScope = options?.authorityScope ?? 'session';
+    return {
+        shouldCommit(projection) {
+            const totals = projection.voteTotals();
+            const winner = projection.majorityWinner();
+            if (!winner)
+                return false;
+            return (totals[winner] ?? 0) >= quorum;
+        },
+        async decideCommitment(projection) {
+            const winner = projection.majorityWinner();
+            const proposal = winner ? projection.proposals.get(winner) : undefined;
+            return {
+                action,
+                authorityScope,
+                reason: proposal ? `Majority selected: ${proposal.option}` : 'Majority reached',
+                outcomePositive: (0, envelope_1.inferOutcomePositive)(action),
+            };
+        },
+    };
+}

package/dist/agent/transports.d.ts

@@ -0,0 +1,35 @@
+import type { AuthConfig } from '../auth';
+import type { MacpClient } from '../client';
+import type { IncomingMessage } from './types';
+export interface TransportAdapter {
+    start(): AsyncIterable<IncomingMessage>;
+    stop(): Promise<void>;
+}
+export declare class GrpcTransportAdapter implements TransportAdapter {
+    private readonly client;
+    private readonly sessionId;
+    private readonly auth?;
+    private stream;
+    private seq;
+    constructor(client: MacpClient, sessionId: string, auth?: AuthConfig | undefined);
+    start(): AsyncIterable<IncomingMessage>;
+    stop(): Promise<void>;
+}
+export interface HttpPollingConfig {
+    baseUrl: string;
+    sessionId: string;
+    participantId: string;
+    pollIntervalMs: number;
+    authToken?: string;
+}
+export declare class HttpTransportAdapter implements TransportAdapter {
+    private readonly config;
+    private stopped;
+    private seq;
+    private lastSeq;
+    constructor(config: HttpPollingConfig);
+    start(): AsyncIterable<IncomingMessage>;
+    stop(): Promise<void>;
+    private tryParsePayload;
+    private sleep;
+}