macp-sdk-typescript 0.2.0 → 0.3.0

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,13 @@ 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 ?? [],
     };
 }
-// ── Builder helpers ─────────────────────────────────────────────────
 function buildDecisionPolicy(policyId, description, rules) {
     const rulesJson = {
         voting: {
@@ -38,7 +38,7 @@ function buildDecisionPolicy(policyId, description, rules) {
         policyId,
         mode: 'macp.mode.decision.v1',
         description,
-        rules: Buffer.from(JSON.stringify(rulesJson)),
+        rules: JSON.stringify(rulesJson),
         schemaVersion: 1,
     };
 }
@@ -58,7 +58,7 @@ function buildQuorumPolicy(policyId, description, rules) {
         policyId,
         mode: 'macp.mode.quorum.v1',
         description,
-        rules: Buffer.from(JSON.stringify(rulesJson)),
+        rules: JSON.stringify(rulesJson),
         schemaVersion: 1,
     };
 }
@@ -79,7 +79,7 @@ function buildProposalPolicy(policyId, description, rules) {
         policyId,
         mode: 'macp.mode.proposal.v1',
         description,
-        rules: Buffer.from(JSON.stringify(rulesJson)),
+        rules: JSON.stringify(rulesJson),
         schemaVersion: 1,
     };
 }
@@ -97,7 +97,7 @@ function buildTaskPolicy(policyId, description, rules) {
         policyId,
         mode: 'macp.mode.task.v1',
         description,
-        rules: Buffer.from(JSON.stringify(rulesJson)),
+        rules: JSON.stringify(rulesJson),
         schemaVersion: 1,
     };
 }
@@ -112,7 +112,7 @@ function buildHandoffPolicy(policyId, description, rules) {
         policyId,
         mode: 'macp.mode.handoff.v1',
         description,
-        rules: Buffer.from(JSON.stringify(rulesJson)),
+        rules: JSON.stringify(rulesJson),
         schemaVersion: 1,
     };
 }

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

@@ -24,7 +24,8 @@ export declare class ProposalSession {
         intent: string;
         participants: string[];
         ttlMs: number;
-        context?: Buffer | string | Record<string, unknown>;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         roots?: {
             uri: string;
             name?: string;

package/dist/proposal.js

@@ -47,7 +47,8 @@ class ProposalSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
-            context: input.context,
+            contextId: input.contextId,
+            extensions: input.extensions,
             roots: input.roots,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,

package/dist/quorum.d.ts

@@ -24,7 +24,8 @@ export declare class QuorumSession {
         intent: string;
         participants: string[];
         ttlMs: number;
-        context?: Buffer | string | Record<string, unknown>;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         roots?: {
             uri: string;
             name?: string;

package/dist/quorum.js

@@ -47,7 +47,8 @@ class QuorumSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
-            context: input.context,
+            contextId: input.contextId,
+            extensions: input.extensions,
             roots: input.roots,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,

package/dist/task.d.ts

@@ -24,14 +24,15 @@ export declare class TaskSession {
         intent: string;
         participants: string[];
         ttlMs: number;
-        context?: Buffer | string | Record<string, unknown>;
+        contextId?: string;
+        extensions?: Record<string, Buffer>;
         roots?: {
             uri: string;
             name?: string;
         }[];
         sender?: string;
     }): Promise<Ack>;
-    request(input: TaskRequestPayload & {
+    requestTask(input: TaskRequestPayload & {
         sender?: string;
         auth?: AuthConfig;
     }): Promise<Ack>;
@@ -43,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>;

package/dist/task.js

@@ -47,7 +47,8 @@ class TaskSession {
             intent: input.intent,
             participants: input.participants,
             ttlMs: input.ttlMs,
-            context: input.context,
+            contextId: input.contextId,
+            extensions: input.extensions,
             roots: input.roots,
             modeVersion: this.modeVersion,
             configurationVersion: this.configurationVersion,
@@ -62,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);
@@ -97,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,
@@ -108,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,
@@ -119,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,

package/dist/types.d.ts

@@ -45,6 +45,8 @@ export interface SessionMetadata {
     participants?: string[];
     participantActivity?: ParticipantActivity[];
     initiator?: string;
+    contextId?: string;
+    extensionKeys?: string[];
 }
 export interface ModeDescriptor {
     mode: string;
@@ -93,7 +95,8 @@ export interface SessionStartPayload {
     configurationVersion: string;
     policyVersion?: string;
     ttlMs: number;
-    context?: Buffer;
+    contextId?: string;
+    extensions?: Record<string, Buffer>;
     roots?: Root[];
 }
 export interface CommitmentPayload {
@@ -250,7 +253,7 @@ export interface PolicyDescriptor {
     policyId: string;
     mode: string;
     description: string;
-    rules: Buffer | Uint8Array;
+    rules: string;
     schemaVersion: number;
     registeredAtUnixMs?: number;
 }
@@ -261,3 +264,9 @@ export interface RegistryChanged {
 export interface RootsChanged {
     observedAtUnixMs: string;
 }
+export type SessionLifecycleEventType = 'EVENT_TYPE_UNSPECIFIED' | 'EVENT_TYPE_CREATED' | 'EVENT_TYPE_RESOLVED' | 'EVENT_TYPE_EXPIRED';
+export interface SessionLifecycleEvent {
+    eventType: SessionLifecycleEventType;
+    session: SessionMetadata;
+    observedAtUnixMs: string;
+}

package/dist/watchers.d.ts

@@ -1,6 +1,6 @@
 import type { AuthConfig } from './auth';
 import type { MacpClient } from './client';
-import type { Envelope, PolicyDescriptor, RegistryChanged, RootsChanged } from './types';
+import type { Envelope, PolicyDescriptor, RegistryChanged, RootsChanged, SessionLifecycleEvent } from './types';
 export declare class ModeRegistryWatcher {
     private readonly client;
     private readonly auth?;
@@ -45,3 +45,25 @@ export declare class PolicyWatcher {
     watch(handler: (change: PolicyChange) => void | Promise<void>): Promise<void>;
     nextChange(): Promise<PolicyChange>;
 }
+export declare class SessionLifecycleWatcher {
+    private readonly client;
+    private readonly auth?;
+    private deprecatedEventsWarned;
+    private deprecatedNextEventWarned;
+    constructor(client: MacpClient, options?: {
+        auth?: AuthConfig;
+    });
+    changes(signal?: AbortSignal): AsyncGenerator<SessionLifecycleEvent, void, void>;
+    watch(handler: (event: SessionLifecycleEvent) => void | Promise<void>): Promise<void>;
+    nextChange(): Promise<SessionLifecycleEvent>;
+    /**
+     * @deprecated Use {@link changes} — renamed for parity with python-sdk's
+     * `SessionLifecycleWatcher.changes()` and the uniform `changes()` name
+     * used by all other watchers in both SDKs. Will be removed in 0.5.0.
+     */
+    events(signal?: AbortSignal): AsyncGenerator<SessionLifecycleEvent, void, void>;
+    /**
+     * @deprecated Use {@link nextChange}. Will be removed in 0.5.0.
+     */
+    nextEvent(): Promise<SessionLifecycleEvent>;
+}

package/dist/watchers.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PolicyWatcher = exports.SignalWatcher = exports.RootsWatcher = exports.ModeRegistryWatcher = void 0;
+exports.SessionLifecycleWatcher = exports.PolicyWatcher = exports.SignalWatcher = exports.RootsWatcher = exports.ModeRegistryWatcher = void 0;
+const logging_1 = require("./logging");
 function serverStreamToAsyncGenerator(stream) {
     const queue = [];
     let resolve = null;
@@ -174,3 +175,60 @@ class PolicyWatcher {
     }
 }
 exports.PolicyWatcher = PolicyWatcher;
+class SessionLifecycleWatcher {
+    client;
+    auth;
+    deprecatedEventsWarned = false;
+    deprecatedNextEventWarned = false;
+    constructor(client, options) {
+        this.client = client;
+        this.auth = options?.auth;
+    }
+    async *changes(signal) {
+        const stream = this.client.watchSessions(this.auth);
+        if (signal) {
+            signal.addEventListener('abort', () => stream.cancel(), { once: true });
+        }
+        const gen = serverStreamToAsyncGenerator(stream);
+        for await (const response of gen) {
+            if (response.event)
+                yield response.event;
+        }
+    }
+    async watch(handler) {
+        for await (const event of this.changes()) {
+            await handler(event);
+        }
+    }
+    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 session lifecycle event');
+        return result.value;
+    }
+    /**
+     * @deprecated Use {@link changes} — renamed for parity with python-sdk's
+     * `SessionLifecycleWatcher.changes()` and the uniform `changes()` name
+     * used by all other watchers in both SDKs. Will be removed in 0.5.0.
+     */
+    async *events(signal) {
+        if (!this.deprecatedEventsWarned) {
+            this.deprecatedEventsWarned = true;
+            logging_1.logger.warn('[deprecated] SessionLifecycleWatcher.events() — use changes() instead');
+        }
+        yield* this.changes(signal);
+    }
+    /**
+     * @deprecated Use {@link nextChange}. Will be removed in 0.5.0.
+     */
+    async nextEvent() {
+        if (!this.deprecatedNextEventWarned) {
+            this.deprecatedNextEventWarned = true;
+            logging_1.logger.warn('[deprecated] SessionLifecycleWatcher.nextEvent() — use nextChange() instead');
+        }
+        return this.nextChange();
+    }
+}
+exports.SessionLifecycleWatcher = SessionLifecycleWatcher;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macp-sdk-typescript",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript SDK for the MACP Rust runtime",
   "license": "Apache-2.0",
   "type": "commonjs",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@grpc/grpc-js": "^1.14.3",
     "@grpc/proto-loader": "^0.8.0",
-    "@multiagentcoordinationprotocol/proto": "^0.1.0",
+    "@multiagentcoordinationprotocol/proto": "^0.1.2",
     "protobufjs": "^8.0.0"
   },
   "devDependencies": {