macp-sdk-typescript 0.2.0

package/dist/projections/quorum.d.ts

@@ -0,0 +1,36 @@
+import type { Envelope } from '../types';
+import type { ProtoRegistry } from '../proto-registry';
+export interface ApprovalRequestRecord {
+    requestId: string;
+    action: string;
+    summary: string;
+    requiredApprovals: number;
+    sender: string;
+}
+export interface BallotRecord {
+    requestId: string;
+    vote: 'approve' | 'reject' | 'abstain';
+    reason?: string;
+    sender: string;
+}
+export declare class QuorumProjection {
+    readonly requests: Map<string, ApprovalRequestRecord>;
+    readonly ballots: Map<string, Map<string, BallotRecord>>;
+    readonly transcript: Envelope[];
+    phase: 'Pending' | 'Voting' | 'Committed';
+    commitment?: Record<string, unknown>;
+    applyEnvelope(envelope: Envelope, protoRegistry: ProtoRegistry): void;
+    get isCommitted(): boolean;
+    get isPositiveOutcome(): boolean | undefined;
+    private setBallot;
+    approvalCount(requestId: string): number;
+    rejectionCount(requestId: string): number;
+    abstentionCount(requestId: string): number;
+    hasQuorum(requestId: string): boolean;
+    threshold(requestId: string): number;
+    votedSenders(requestId: string): string[];
+    remainingVotesNeeded(requestId: string): number;
+    commitmentReady(requestId: string): boolean;
+    isThresholdUnreachable(requestId: string, totalEligible: number): boolean;
+    private countVotes;
+}

package/dist/projections/quorum.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuorumProjection = void 0;
+const constants_1 = require("../constants");
+class QuorumProjection {
+    requests = new Map();
+    ballots = new Map();
+    transcript = [];
+    phase = 'Pending';
+    commitment;
+    applyEnvelope(envelope, protoRegistry) {
+        if (envelope.mode !== constants_1.MODE_QUORUM)
+            return;
+        this.transcript.push(envelope);
+        const payload = protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload);
+        switch (envelope.messageType) {
+            case 'ApprovalRequest': {
+                const record = payload;
+                this.requests.set(record.requestId, { ...record, sender: envelope.sender });
+                this.phase = 'Voting';
+                break;
+            }
+            case 'Approve': {
+                const record = payload;
+                this.setBallot(record.requestId, envelope.sender, 'approve', record.reason);
+                break;
+            }
+            case 'Reject': {
+                const record = payload;
+                this.setBallot(record.requestId, envelope.sender, 'reject', record.reason);
+                break;
+            }
+            case 'Abstain': {
+                const record = payload;
+                this.setBallot(record.requestId, envelope.sender, 'abstain', record.reason);
+                break;
+            }
+            case 'Commitment': {
+                this.commitment = payload;
+                this.phase = 'Committed';
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    get isCommitted() {
+        return this.commitment !== undefined;
+    }
+    get isPositiveOutcome() {
+        if (!this.commitment)
+            return undefined;
+        const val = this.commitment.outcomePositive ??
+            this.commitment.outcome_positive;
+        return val !== undefined ? Boolean(val) : true;
+    }
+    setBallot(requestId, sender, vote, reason) {
+        const senderMap = this.ballots.get(requestId) ?? new Map();
+        senderMap.set(sender, { requestId, vote, reason, sender });
+        this.ballots.set(requestId, senderMap);
+    }
+    approvalCount(requestId) {
+        return this.countVotes(requestId, 'approve');
+    }
+    rejectionCount(requestId) {
+        return this.countVotes(requestId, 'reject');
+    }
+    abstentionCount(requestId) {
+        return this.countVotes(requestId, 'abstain');
+    }
+    hasQuorum(requestId) {
+        const req = this.requests.get(requestId);
+        if (!req)
+            return false;
+        return this.approvalCount(requestId) >= req.requiredApprovals;
+    }
+    threshold(requestId) {
+        return this.requests.get(requestId)?.requiredApprovals ?? 0;
+    }
+    votedSenders(requestId) {
+        const senderMap = this.ballots.get(requestId);
+        return senderMap ? [...senderMap.keys()] : [];
+    }
+    remainingVotesNeeded(requestId) {
+        const req = this.requests.get(requestId);
+        if (!req)
+            return 0;
+        return Math.max(0, req.requiredApprovals - this.approvalCount(requestId));
+    }
+    commitmentReady(requestId) {
+        return this.hasQuorum(requestId) && this.phase !== 'Committed';
+    }
+    isThresholdUnreachable(requestId, totalEligible) {
+        const req = this.requests.get(requestId);
+        if (!req)
+            return false;
+        const remaining = totalEligible - this.votedSenders(requestId).length;
+        return this.approvalCount(requestId) + remaining < req.requiredApprovals;
+    }
+    countVotes(requestId, vote) {
+        const senderMap = this.ballots.get(requestId);
+        if (!senderMap)
+            return 0;
+        return [...senderMap.values()].filter((b) => b.vote === vote).length;
+    }
+}
+exports.QuorumProjection = QuorumProjection;

package/dist/projections/task.d.ts

@@ -0,0 +1,54 @@
+import type { Envelope } from '../types';
+import type { ProtoRegistry } from '../proto-registry';
+export interface TaskRecord {
+    taskId: string;
+    title: string;
+    instructions: string;
+    requestedAssignee?: string;
+    assignee?: string;
+    deadlineUnixMs?: number;
+    status: 'requested' | 'accepted' | 'rejected' | 'in_progress' | 'completed' | 'failed';
+    progress: number;
+    sender: string;
+}
+export interface TaskUpdateRecord {
+    taskId: string;
+    status: string;
+    progress: number;
+    message?: string;
+    sender: string;
+}
+export interface TaskCompletionRecord {
+    taskId: string;
+    assignee: string;
+    summary?: string;
+    sender: string;
+}
+export interface TaskFailureRecord {
+    taskId: string;
+    assignee: string;
+    errorCode?: string;
+    reason?: string;
+    retryable: boolean;
+    sender: string;
+}
+export declare class TaskProjection {
+    readonly tasks: Map<string, TaskRecord>;
+    readonly updates: TaskUpdateRecord[];
+    readonly completions: TaskCompletionRecord[];
+    readonly failures: TaskFailureRecord[];
+    readonly transcript: Envelope[];
+    phase: 'Pending' | 'Requested' | 'InProgress' | 'Completed' | 'Failed' | 'Committed';
+    commitment?: Record<string, unknown>;
+    applyEnvelope(envelope: Envelope, protoRegistry: ProtoRegistry): void;
+    get isCommitted(): boolean;
+    get isPositiveOutcome(): boolean | undefined;
+    getTask(taskId: string): TaskRecord | undefined;
+    isComplete(taskId: string): boolean;
+    isFailed(taskId: string): boolean;
+    isRetryable(taskId: string): boolean;
+    progressOf(taskId: string): number;
+    activeTasks(): TaskRecord[];
+    isAccepted(taskId: string): boolean;
+    latestProgress(): number | undefined;
+}

package/dist/projections/task.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskProjection = void 0;
+const constants_1 = require("../constants");
+class TaskProjection {
+    tasks = new Map();
+    updates = [];
+    completions = [];
+    failures = [];
+    transcript = [];
+    phase = 'Pending';
+    commitment;
+    applyEnvelope(envelope, protoRegistry) {
+        if (envelope.mode !== constants_1.MODE_TASK)
+            return;
+        this.transcript.push(envelope);
+        const payload = protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload);
+        switch (envelope.messageType) {
+            case 'TaskRequest': {
+                const record = payload;
+                this.tasks.set(record.taskId, {
+                    taskId: record.taskId,
+                    title: record.title,
+                    instructions: record.instructions,
+                    requestedAssignee: record.requestedAssignee,
+                    deadlineUnixMs: record.deadlineUnixMs,
+                    status: 'requested',
+                    progress: 0,
+                    sender: envelope.sender,
+                });
+                this.phase = 'Requested';
+                break;
+            }
+            case 'TaskAccept': {
+                const record = payload;
+                const task = this.tasks.get(record.taskId);
+                if (task) {
+                    task.assignee = record.assignee;
+                    task.status = 'accepted';
+                }
+                this.phase = 'InProgress';
+                break;
+            }
+            case 'TaskReject': {
+                const record = payload;
+                const task = this.tasks.get(record.taskId);
+                if (task)
+                    task.status = 'rejected';
+                break;
+            }
+            case 'TaskUpdate': {
+                const record = payload;
+                this.updates.push({ ...record, sender: envelope.sender });
+                const task = this.tasks.get(record.taskId);
+                if (task) {
+                    task.progress = record.progress;
+                    task.status = 'in_progress';
+                }
+                break;
+            }
+            case 'TaskComplete': {
+                const record = payload;
+                this.completions.push({ ...record, sender: envelope.sender });
+                const task = this.tasks.get(record.taskId);
+                if (task) {
+                    task.status = 'completed';
+                    task.progress = 1;
+                }
+                this.phase = 'Completed';
+                break;
+            }
+            case 'TaskFail': {
+                const record = payload;
+                this.failures.push({ ...record, retryable: record.retryable ?? false, sender: envelope.sender });
+                const task = this.tasks.get(record.taskId);
+                if (task)
+                    task.status = 'failed';
+                this.phase = 'Failed';
+                break;
+            }
+            case 'Commitment': {
+                this.commitment = payload;
+                this.phase = 'Committed';
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    get isCommitted() {
+        return this.commitment !== undefined;
+    }
+    get isPositiveOutcome() {
+        if (!this.commitment)
+            return undefined;
+        const val = this.commitment.outcomePositive ??
+            this.commitment.outcome_positive;
+        return val !== undefined ? Boolean(val) : true;
+    }
+    getTask(taskId) {
+        return this.tasks.get(taskId);
+    }
+    isComplete(taskId) {
+        return this.tasks.get(taskId)?.status === 'completed';
+    }
+    isFailed(taskId) {
+        return this.tasks.get(taskId)?.status === 'failed';
+    }
+    isRetryable(taskId) {
+        return this.failures.some((f) => f.taskId === taskId && f.retryable);
+    }
+    progressOf(taskId) {
+        return this.tasks.get(taskId)?.progress ?? 0;
+    }
+    activeTasks() {
+        const active = new Set(['requested', 'accepted', 'in_progress']);
+        return [...this.tasks.values()].filter((t) => active.has(t.status));
+    }
+    isAccepted(taskId) {
+        const status = this.tasks.get(taskId)?.status;
+        return status === 'accepted' || status === 'in_progress';
+    }
+    latestProgress() {
+        return this.updates[this.updates.length - 1]?.progress;
+    }
+}
+exports.TaskProjection = TaskProjection;

package/dist/projections.d.ts

@@ -0,0 +1,5 @@
+export * from './projections/decision';
+export * from './projections/proposal';
+export * from './projections/task';
+export * from './projections/handoff';
+export * from './projections/quorum';

package/dist/projections.js

@@ -0,0 +1,21 @@
+"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 });
+__exportStar(require("./projections/decision"), exports);
+__exportStar(require("./projections/proposal"), exports);
+__exportStar(require("./projections/task"), exports);
+__exportStar(require("./projections/handoff"), exports);
+__exportStar(require("./projections/quorum"), exports);

package/dist/proposal.d.ts

@@ -0,0 +1,69 @@
+import { type AuthConfig } from './auth';
+import type { MacpClient, MacpStream } from './client';
+import { ProposalProjection } from './projections/proposal';
+import type { AcceptPayload, Ack, CounterProposalPayload, ProposalModeProposalPayload, RejectPayload, SessionMetadata, WithdrawPayload } from './types';
+interface ProposalSessionOptions {
+    sessionId?: string;
+    modeVersion?: string;
+    configurationVersion?: string;
+    policyVersion?: string;
+    auth?: AuthConfig;
+}
+export declare class ProposalSession {
+    readonly client: MacpClient;
+    readonly sessionId: string;
+    readonly modeVersion: string;
+    readonly configurationVersion: string;
+    readonly policyVersion: string;
+    readonly auth?: AuthConfig;
+    readonly projection: ProposalProjection;
+    constructor(client: MacpClient, options?: ProposalSessionOptions);
+    private senderFor;
+    private sendAndTrack;
+    start(input: {
+        intent: string;
+        participants: string[];
+        ttlMs: number;
+        context?: Buffer | string | Record<string, unknown>;
+        roots?: {
+            uri: string;
+            name?: string;
+        }[];
+        sender?: string;
+    }): Promise<Ack>;
+    propose(input: ProposalModeProposalPayload & {
+        sender?: string;
+        auth?: AuthConfig;
+    }): Promise<Ack>;
+    counterPropose(input: CounterProposalPayload & {
+        sender?: string;
+        auth?: AuthConfig;
+    }): Promise<Ack>;
+    accept(input: AcceptPayload & {
+        sender?: string;
+        auth?: AuthConfig;
+    }): Promise<Ack>;
+    reject(input: RejectPayload & {
+        sender?: string;
+        auth?: AuthConfig;
+    }): Promise<Ack>;
+    withdraw(input: WithdrawPayload & {
+        sender?: string;
+        auth?: AuthConfig;
+    }): Promise<Ack>;
+    commit(input: {
+        action: string;
+        authorityScope: string;
+        reason: string;
+        commitmentId?: string;
+        outcomePositive?: boolean;
+        sender?: string;
+        auth?: AuthConfig;
+    }): Promise<Ack>;
+    metadata(auth?: AuthConfig): Promise<{
+        metadata: SessionMetadata;
+    }>;
+    cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    openStream(auth?: AuthConfig): MacpStream;
+}
+export {};

package/dist/proposal.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProposalSession = void 0;
+const auth_1 = require("./auth");
+const constants_1 = require("./constants");
+const envelope_1 = require("./envelope");
+const proposal_1 = require("./projections/proposal");
+const validation_1 = require("./validation");
+class ProposalSession {
+    client;
+    sessionId;
+    modeVersion;
+    configurationVersion;
+    policyVersion;
+    auth;
+    projection = new proposal_1.ProposalProjection();
+    constructor(client, options = {}) {
+        this.client = client;
+        if (options.sessionId)
+            (0, validation_1.validateSessionId)(options.sessionId);
+        this.sessionId = options.sessionId ?? (0, envelope_1.newSessionId)();
+        this.modeVersion = options.modeVersion ?? constants_1.DEFAULT_MODE_VERSION;
+        this.configurationVersion = options.configurationVersion ?? constants_1.DEFAULT_CONFIGURATION_VERSION;
+        this.policyVersion = options.policyVersion ?? constants_1.DEFAULT_POLICY_VERSION;
+        this.auth = options.auth;
+    }
+    senderFor(sender, auth) {
+        const effectiveAuth = auth ?? this.auth ?? this.client.auth;
+        (0, auth_1.assertSenderMatchesIdentity)(effectiveAuth, sender);
+        return sender ?? (0, auth_1.authSender)(effectiveAuth) ?? '';
+    }
+    async sendAndTrack(envelope, auth) {
+        const ack = await this.client.send(envelope, { auth: auth ?? this.auth });
+        if (ack.ok)
+            this.projection.applyEnvelope(envelope, this.client.protoRegistry);
+        return ack;
+    }
+    async start(input) {
+        (0, validation_1.validateSessionStart)({
+            intent: input.intent,
+            participants: input.participants,
+            ttlMs: input.ttlMs,
+            modeVersion: this.modeVersion,
+            configurationVersion: this.configurationVersion,
+        });
+        const payload = (0, envelope_1.buildSessionStartPayload)({
+            intent: input.intent,
+            participants: input.participants,
+            ttlMs: input.ttlMs,
+            context: input.context,
+            roots: input.roots,
+            modeVersion: this.modeVersion,
+            configurationVersion: this.configurationVersion,
+            policyVersion: this.policyVersion,
+        });
+        const envelope = (0, envelope_1.buildEnvelope)({
+            mode: constants_1.MODE_PROPOSAL,
+            messageType: 'SessionStart',
+            sessionId: this.sessionId,
+            sender: this.senderFor(input.sender),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_PROPOSAL, 'SessionStart', (0, envelope_1.toProtoPayload)(payload)),
+        });
+        return this.sendAndTrack(envelope, this.auth);
+    }
+    async propose(input) {
+        (0, validation_1.validateRequiredField)('proposalId', input.proposalId);
+        (0, validation_1.validateRequiredField)('title', input.title);
+        const envelope = (0, envelope_1.buildEnvelope)({
+            mode: constants_1.MODE_PROPOSAL,
+            messageType: 'Proposal',
+            sessionId: this.sessionId,
+            sender: this.senderFor(input.sender, input.auth),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_PROPOSAL, 'Proposal', (0, envelope_1.toProtoPayload)(input)),
+        });
+        return this.sendAndTrack(envelope, input.auth);
+    }
+    async counterPropose(input) {
+        (0, validation_1.validateRequiredField)('proposalId', input.proposalId);
+        (0, validation_1.validateRequiredField)('title', input.title);
+        const envelope = (0, envelope_1.buildEnvelope)({
+            mode: constants_1.MODE_PROPOSAL,
+            messageType: 'CounterProposal',
+            sessionId: this.sessionId,
+            sender: this.senderFor(input.sender, input.auth),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_PROPOSAL, 'CounterProposal', (0, envelope_1.toProtoPayload)(input)),
+        });
+        return this.sendAndTrack(envelope, input.auth);
+    }
+    async accept(input) {
+        (0, validation_1.validateRequiredField)('proposalId', input.proposalId);
+        const envelope = (0, envelope_1.buildEnvelope)({
+            mode: constants_1.MODE_PROPOSAL,
+            messageType: 'Accept',
+            sessionId: this.sessionId,
+            sender: this.senderFor(input.sender, input.auth),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_PROPOSAL, 'Accept', (0, envelope_1.toProtoPayload)(input)),
+        });
+        return this.sendAndTrack(envelope, input.auth);
+    }
+    async reject(input) {
+        (0, validation_1.validateRequiredField)('proposalId', input.proposalId);
+        const envelope = (0, envelope_1.buildEnvelope)({
+            mode: constants_1.MODE_PROPOSAL,
+            messageType: 'Reject',
+            sessionId: this.sessionId,
+            sender: this.senderFor(input.sender, input.auth),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_PROPOSAL, 'Reject', (0, envelope_1.toProtoPayload)(input)),
+        });
+        return this.sendAndTrack(envelope, input.auth);
+    }
+    async withdraw(input) {
+        (0, validation_1.validateRequiredField)('proposalId', input.proposalId);
+        const envelope = (0, envelope_1.buildEnvelope)({
+            mode: constants_1.MODE_PROPOSAL,
+            messageType: 'Withdraw',
+            sessionId: this.sessionId,
+            sender: this.senderFor(input.sender, input.auth),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_PROPOSAL, 'Withdraw', (0, envelope_1.toProtoPayload)(input)),
+        });
+        return this.sendAndTrack(envelope, input.auth);
+    }
+    async commit(input) {
+        const payload = (0, envelope_1.buildCommitmentPayload)({
+            action: input.action,
+            authorityScope: input.authorityScope,
+            reason: input.reason,
+            commitmentId: input.commitmentId,
+            outcomePositive: input.outcomePositive,
+            modeVersion: this.modeVersion,
+            configurationVersion: this.configurationVersion,
+            policyVersion: this.policyVersion,
+        });
+        const envelope = (0, envelope_1.buildEnvelope)({
+            mode: constants_1.MODE_PROPOSAL,
+            messageType: 'Commitment',
+            sessionId: this.sessionId,
+            sender: this.senderFor(input.sender, input.auth),
+            payload: this.client.protoRegistry.encodeKnownPayload(constants_1.MODE_PROPOSAL, 'Commitment', (0, envelope_1.toProtoPayload)(payload)),
+        });
+        return this.sendAndTrack(envelope, input.auth);
+    }
+    metadata(auth) {
+        return this.client.getSession(this.sessionId, { auth: auth ?? this.auth });
+    }
+    async cancel(reason = '', auth) {
+        return this.client.cancelSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    openStream(auth) {
+        return this.client.openStream({ auth: auth ?? this.auth });
+    }
+}
+exports.ProposalSession = ProposalSession;

package/dist/proto-registry.d.ts

@@ -0,0 +1,12 @@
+export declare class ProtoRegistry {
+    readonly protoDir: string;
+    private root;
+    constructor(protoDir?: string);
+    getKnownTypeName(mode: string, messageType: string): string | undefined;
+    encodeMessage(typeName: string, value: Record<string, unknown>): Buffer;
+    decodeMessage(typeName: string, payload: Buffer): Record<string, unknown>;
+    encodeKnownPayload(mode: string, messageType: string, value: Record<string, unknown>): Buffer;
+    decodeKnownPayload(mode: string, messageType: string, payload: Buffer): Record<string, unknown> | undefined;
+    private lookupType;
+    private tryDecodeUtf8;
+}