macp-sdk-typescript 0.2.2 → 0.4.0

package/dist/handoff.js

@@ -6,14 +6,6 @@ const constants_1 = require("./constants");
 const envelope_1 = require("./envelope");
 const handoff_1 = require("./projections/handoff");
 const validation_1 = require("./validation");
-let sendContextWarned = false;
-function warnSendContextOnce() {
-    if (sendContextWarned)
-        return;
-    sendContextWarned = true;
-    // eslint-disable-next-line no-console
-    console.warn('[macp-sdk-typescript] HandoffSession.sendContext() is deprecated and will be removed in 0.4.0. Use addContext() instead.');
-}
 class HandoffSession {
     client;
     sessionId;
@@ -95,14 +87,6 @@ class HandoffSession {
         });
         return this.sendAndTrack(envelope, input.auth);
     }
-    /**
-     * @deprecated Use {@link addContext} instead. Scheduled for removal in 0.4.0.
-     * First call logs a one-shot warning to guide migrations without spamming long-lived processes.
-     */
-    async sendContext(input) {
-        warnSendContextOnce();
-        return this.addContext(input);
-    }
     async acceptHandoff(input) {
         (0, validation_1.validateRequiredField)('handoffId', input.handoffId);
         const envelope = (0, envelope_1.buildEnvelope)({
@@ -154,6 +138,26 @@ class HandoffSession {
             raiseOnNack: true,
         });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    async suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    async resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-export * from './auth';
+export { Auth, type AuthConfig, type BearerAuthOptions } from './auth';
+export * from './base-session';
 export * from './client';
 export * from './constants';
 export * from './decision';
 export * from './envelope';
 export * from './errors';
 export * from './handoff';
+export * from './logging';
 export * from './policy';
 export * from './projections';
 export * from './proposal';

package/dist/index.js

@@ -36,14 +36,22 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agent = void 0;
-__exportStar(require("./auth"), exports);
+exports.agent = exports.Auth = void 0;
+// Auth: export only the public constructors and types. The helpers
+// `validateAuth`, `authSender`, `assertSenderMatchesIdentity`, and
+// `metadataFromAuth` are SDK-internal — importable from the `./auth`
+// submodule if needed, but intentionally absent from the top-level surface
+// to match python-sdk's `__all__` (which only exposes `AuthConfig`).
+var auth_1 = require("./auth");
+Object.defineProperty(exports, "Auth", { enumerable: true, get: function () { return auth_1.Auth; } });
+__exportStar(require("./base-session"), exports);
 __exportStar(require("./client"), exports);
 __exportStar(require("./constants"), exports);
 __exportStar(require("./decision"), exports);
 __exportStar(require("./envelope"), exports);
 __exportStar(require("./errors"), exports);
 __exportStar(require("./handoff"), exports);
+__exportStar(require("./logging"), exports);
 __exportStar(require("./policy"), exports);
 __exportStar(require("./projections"), exports);
 __exportStar(require("./proposal"), exports);

package/dist/logging.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Structured logger for the MACP SDK.
+ *
+ * Parity with python-sdk's `macp_sdk._logging.logger` + `configure_logging()`:
+ * production Node apps need controllable log levels (silent by default-ish,
+ * opt-in verbose) and the ability to re-route to Pino / Winston / etc.
+ */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+export type LogSink = (level: Exclude<LogLevel, 'silent'>, args: unknown[]) => void;
+export declare const logger: {
+    error: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+};
+export declare function configureLogging(options: {
+    level?: LogLevel;
+    sink?: LogSink;
+}): void;
+/** Test-only: reset to env-derived level + default sink. */
+export declare function _resetLoggingForTests(): void;

package/dist/logging.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Structured logger for the MACP SDK.
+ *
+ * Parity with python-sdk's `macp_sdk._logging.logger` + `configure_logging()`:
+ * production Node apps need controllable log levels (silent by default-ish,
+ * opt-in verbose) and the ability to re-route to Pino / Winston / etc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+exports.configureLogging = configureLogging;
+exports._resetLoggingForTests = _resetLoggingForTests;
+const LEVEL_ORDER = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+const defaultSink = (level, args) => {
+    const method = level === 'debug' || level === 'info' ? 'log' : level;
+    // eslint-disable-next-line no-console
+    (console[method] ?? console.log)('[macp-sdk]', ...args);
+};
+function envLevel() {
+    const raw = typeof process !== 'undefined' ? process.env?.MACP_LOG_LEVEL?.toLowerCase() : undefined;
+    if (raw && raw in LEVEL_ORDER)
+        return raw;
+    return 'warn';
+}
+const state = {
+    level: envLevel(),
+    sink: defaultSink,
+};
+function shouldLog(level) {
+    return LEVEL_ORDER[state.level] >= LEVEL_ORDER[level];
+}
+function emit(level, args) {
+    if (!shouldLog(level))
+        return;
+    state.sink(level, args);
+}
+exports.logger = {
+    error: (...args) => emit('error', args),
+    warn: (...args) => emit('warn', args),
+    info: (...args) => emit('info', args),
+    debug: (...args) => emit('debug', args),
+};
+function configureLogging(options) {
+    if (options.level !== undefined) {
+        if (!(options.level in LEVEL_ORDER)) {
+            throw new Error(`configureLogging: unknown level "${options.level}"`);
+        }
+        state.level = options.level;
+    }
+    if (options.sink !== undefined) {
+        state.sink = options.sink;
+    }
+}
+/** Test-only: reset to env-derived level + default sink. */
+function _resetLoggingForTests() {
+    state.level = envLevel();
+    state.sink = defaultSink;
+}

package/dist/policy.d.ts

@@ -1,9 +1,11 @@
 import type { PolicyDescriptor } from './types';
-export interface CommitmentRulesInput {
+export interface CommitmentRules {
     authority?: 'initiator_only' | 'any_participant' | 'designated_role';
     designatedRoles?: string[];
+    /** Decision-specific: require quorum before commit. Ignored for other modes. */
+    requireVoteQuorum?: boolean;
 }
-export interface DecisionVotingRules {
+export interface VotingRules {
     algorithm?: 'none' | 'majority' | 'supermajority' | 'unanimous' | 'weighted' | 'plurality';
     threshold?: number;
     quorum?: {
@@ -12,62 +14,65 @@ export interface DecisionVotingRules {
     };
     weights?: Record<string, number>;
 }
-export interface DecisionObjectionHandling {
+export interface ObjectionHandlingRules {
     criticalSeverityVetoes?: boolean;
     vetoThreshold?: number;
 }
-export interface DecisionEvaluationRules {
+export interface EvaluationRules {
     minimumConfidence?: number;
     requiredBeforeVoting?: boolean;
 }
-export interface DecisionCommitmentRules {
-    authority?: 'initiator_only' | 'any_participant' | 'designated_role';
-    designatedRoles?: string[];
-    requireVoteQuorum?: boolean;
+export interface QuorumThreshold {
+    type: 'n_of_m' | 'percentage' | 'weighted';
+    value: number;
+}
+export interface AbstentionRules {
+    countsTowardQuorum?: boolean;
+    interpretation?: 'neutral' | 'implicit_reject' | 'ignored';
+}
+export interface ProposalAcceptanceRules {
+    criterion?: 'all_parties' | 'counterparty' | 'initiator';
+}
+export interface CounterProposalRules {
+    maxRounds?: number;
+}
+export interface RejectionRules {
+    terminalOnAnyReject?: boolean;
+}
+export interface TaskAssignmentRules {
+    allowReassignmentOnReject?: boolean;
+}
+export interface TaskCompletionRules {
+    requireOutput?: boolean;
+}
+export interface HandoffAcceptanceRules {
+    implicitAcceptTimeoutMs?: number;
 }
 export interface DecisionPolicyRulesInput {
-    voting?: DecisionVotingRules;
-    objectionHandling?: DecisionObjectionHandling;
-    evaluation?: DecisionEvaluationRules;
-    commitment?: DecisionCommitmentRules;
+    voting?: VotingRules;
+    objectionHandling?: ObjectionHandlingRules;
+    evaluation?: EvaluationRules;
+    commitment?: CommitmentRules;
 }
 export interface QuorumPolicyRulesInput {
-    threshold?: {
-        type: 'n_of_m' | 'percentage' | 'weighted';
-        value: number;
-    };
-    abstention?: {
-        countsTowardQuorum?: boolean;
-        interpretation?: 'neutral' | 'implicit_reject' | 'ignored';
-    };
-    commitment?: CommitmentRulesInput;
+    threshold?: QuorumThreshold;
+    abstention?: AbstentionRules;
+    commitment?: CommitmentRules;
 }
 export interface ProposalPolicyRulesInput {
-    acceptance?: {
-        criterion?: 'all_parties' | 'counterparty' | 'initiator';
-    };
-    counterProposal?: {
-        maxRounds?: number;
-    };
-    rejection?: {
-        terminalOnAnyReject?: boolean;
-    };
-    commitment?: CommitmentRulesInput;
+    acceptance?: ProposalAcceptanceRules;
+    counterProposal?: CounterProposalRules;
+    rejection?: RejectionRules;
+    commitment?: CommitmentRules;
 }
 export interface TaskPolicyRulesInput {
-    assignment?: {
-        allowReassignmentOnReject?: boolean;
-    };
-    completion?: {
-        requireOutput?: boolean;
-    };
-    commitment?: CommitmentRulesInput;
+    assignment?: TaskAssignmentRules;
+    completion?: TaskCompletionRules;
+    commitment?: CommitmentRules;
 }
 export interface HandoffPolicyRulesInput {
-    acceptance?: {
-        implicitAcceptTimeoutMs?: number;
-    };
-    commitment?: CommitmentRulesInput;
+    acceptance?: HandoffAcceptanceRules;
+    commitment?: CommitmentRules;
 }
 export declare function buildDecisionPolicy(policyId: string, description: string, rules: DecisionPolicyRulesInput): PolicyDescriptor;
 export declare function buildQuorumPolicy(policyId: string, description: string, rules: QuorumPolicyRulesInput): PolicyDescriptor;

package/dist/policy.js

@@ -5,13 +5,16 @@ exports.buildQuorumPolicy = buildQuorumPolicy;
 exports.buildProposalPolicy = buildProposalPolicy;
 exports.buildTaskPolicy = buildTaskPolicy;
 exports.buildHandoffPolicy = buildHandoffPolicy;
+// ── Builder helpers ─────────────────────────────────────────────────
 function serializeCommitment(commitment) {
     return {
         authority: commitment?.authority ?? 'initiator_only',
         designated_roles: commitment?.designatedRoles ?? [],
+        // Parity with python-sdk `_commitment_dict`: emitted for every mode, not
+        // just decision, so policy JSON is byte-identical across SDKs.
+        require_vote_quorum: commitment?.requireVoteQuorum ?? false,
     };
 }
-// ── Builder helpers ─────────────────────────────────────────────────
 function buildDecisionPolicy(policyId, description, rules) {
     const rulesJson = {
         voting: {
@@ -28,11 +31,7 @@ function buildDecisionPolicy(policyId, description, rules) {
             minimum_confidence: rules.evaluation?.minimumConfidence ?? 0,
             required_before_voting: rules.evaluation?.requiredBeforeVoting ?? false,
         },
-        commitment: {
-            authority: rules.commitment?.authority ?? 'initiator_only',
-            designated_roles: rules.commitment?.designatedRoles ?? [],
-            require_vote_quorum: rules.commitment?.requireVoteQuorum ?? false,
-        },
+        commitment: serializeCommitment(rules.commitment),
     };
     return {
         policyId,

package/dist/projections/base.d.ts

@@ -0,0 +1,20 @@
+import type { ProtoRegistry } from '../proto-registry';
+import type { Envelope } from '../types';
+/**
+ * Abstract base for in-process mode-state tracking — parity with python-sdk's
+ * `macp_sdk.base_projection.BaseProjection`. Maintains a shared transcript,
+ * phase string, and commitment payload; subclasses override `applyMode`
+ * to handle mode-specific envelopes. `SessionStart` and `Commitment` are
+ * handled here so custom modes get the common lifecycle for free.
+ */
+export declare abstract class BaseProjection {
+    readonly transcript: Envelope[];
+    phase: string;
+    commitment?: Record<string, unknown>;
+    protected abstract readonly mode: string;
+    get isCommitted(): boolean;
+    get isPositiveOutcome(): boolean | undefined;
+    applyEnvelope(envelope: Envelope, protoRegistry: ProtoRegistry): void;
+    /** Handle a mode-specific (non-Commitment) envelope. */
+    protected abstract applyMode(envelope: Envelope, protoRegistry: ProtoRegistry): void;
+}

package/dist/projections/base.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseProjection = void 0;
+/**
+ * Abstract base for in-process mode-state tracking — parity with python-sdk's
+ * `macp_sdk.base_projection.BaseProjection`. Maintains a shared transcript,
+ * phase string, and commitment payload; subclasses override `applyMode`
+ * to handle mode-specific envelopes. `SessionStart` and `Commitment` are
+ * handled here so custom modes get the common lifecycle for free.
+ */
+class BaseProjection {
+    transcript = [];
+    phase = '';
+    commitment;
+    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;
+    }
+    applyEnvelope(envelope, protoRegistry) {
+        if (envelope.mode !== this.mode)
+            return;
+        this.transcript.push(envelope);
+        if (envelope.messageType === 'Commitment') {
+            this.commitment = protoRegistry.decodeKnownPayload(envelope.mode, envelope.messageType, envelope.payload);
+            this.phase = 'Committed';
+            return;
+        }
+        this.applyMode(envelope, protoRegistry);
+    }
+}
+exports.BaseProjection = BaseProjection;

package/dist/projections.d.ts

@@ -1,3 +1,4 @@
+export * from './projections/base';
 export * from './projections/decision';
 export * from './projections/proposal';
 export * from './projections/task';

package/dist/projections.js

@@ -14,6 +14,7 @@ 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/base"), exports);
 __exportStar(require("./projections/decision"), exports);
 __exportStar(require("./projections/proposal"), exports);
 __exportStar(require("./projections/task"), exports);

package/dist/proposal.d.ts

@@ -65,6 +65,16 @@ export declare class ProposalSession {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }
 export {};

package/dist/proposal.js

@@ -149,6 +149,26 @@ class ProposalSession {
             raiseOnNack: true,
         });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    async suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    async resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }

package/dist/quorum.d.ts

@@ -61,6 +61,16 @@ export declare class QuorumSession {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }
 export {};

package/dist/quorum.js

@@ -138,6 +138,26 @@ class QuorumSession {
             raiseOnNack: true,
         });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    async suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    async resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }

package/dist/task.d.ts

@@ -32,7 +32,7 @@ export declare class TaskSession {
         }[];
         sender?: string;
     }): Promise<Ack>;
-    request(input: TaskRequestPayload & {
+    requestTask(input: TaskRequestPayload & {
         sender?: string;
         auth?: AuthConfig;
     }): Promise<Ack>;
@@ -44,15 +44,15 @@ export declare class TaskSession {
         sender?: string;
         auth?: AuthConfig;
     }): Promise<Ack>;
-    update(input: TaskUpdatePayload & {
+    updateTask(input: TaskUpdatePayload & {
         sender?: string;
         auth?: AuthConfig;
     }): Promise<Ack>;
-    complete(input: TaskCompletePayload & {
+    completeTask(input: TaskCompletePayload & {
         sender?: string;
         auth?: AuthConfig;
     }): Promise<Ack>;
-    fail(input: TaskFailPayload & {
+    failTask(input: TaskFailPayload & {
         sender?: string;
         auth?: AuthConfig;
     }): Promise<Ack>;
@@ -69,6 +69,16 @@ export declare class TaskSession {
         metadata: SessionMetadata;
     }>;
     cancel(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    suspend(reason?: string, auth?: AuthConfig): Promise<Ack>;
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    resume(reason?: string, auth?: AuthConfig): Promise<Ack>;
     openStream(auth?: AuthConfig): MacpStream;
 }
 export {};

package/dist/task.js

@@ -63,7 +63,7 @@ class TaskSession {
         });
         return this.sendAndTrack(envelope, this.auth);
     }
-    async request(input) {
+    async requestTask(input) {
         (0, validation_1.validateRequiredField)('taskId', input.taskId);
         (0, validation_1.validateRequiredField)('title', input.title);
         (0, validation_1.validateRequiredField)('instructions', input.instructions);
@@ -98,7 +98,7 @@ class TaskSession {
         });
         return this.sendAndTrack(envelope, input.auth);
     }
-    async update(input) {
+    async updateTask(input) {
         (0, validation_1.validateRequiredField)('taskId', input.taskId);
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_TASK,
@@ -109,7 +109,7 @@ class TaskSession {
         });
         return this.sendAndTrack(envelope, input.auth);
     }
-    async complete(input) {
+    async completeTask(input) {
         (0, validation_1.validateRequiredField)('taskId', input.taskId);
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_TASK,
@@ -120,7 +120,7 @@ class TaskSession {
         });
         return this.sendAndTrack(envelope, input.auth);
     }
-    async fail(input) {
+    async failTask(input) {
         (0, validation_1.validateRequiredField)('taskId', input.taskId);
         const envelope = (0, envelope_1.buildEnvelope)({
             mode: constants_1.MODE_TASK,
@@ -160,6 +160,26 @@ class TaskSession {
             raiseOnNack: true,
         });
     }
+    /**
+     * Pause this session via `SuspendSession` (proto 0.1.3+). Non-terminal: the
+     * runtime banks remaining TTL and rejects messages until {@link resume}.
+     */
+    async suspend(reason = '', auth) {
+        return this.client.suspendSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
+    /**
+     * Resume this suspended session via `ResumeSession` (proto 0.1.3+),
+     * restoring `SESSION_STATE_OPEN` and the banked TTL.
+     */
+    async resume(reason = '', auth) {
+        return this.client.resumeSession(this.sessionId, reason, {
+            auth: auth ?? this.auth,
+            raiseOnNack: true,
+        });
+    }
     openStream(auth) {
         return this.client.openStream({ auth: auth ?? this.auth });
     }