macp-sdk-typescript 0.2.2 → 0.4.0

package/dist/types.d.ts

@@ -19,13 +19,24 @@ export interface MacpErrorShape {
     messageId?: string;
     details?: Buffer;
 }
+/**
+ * Lifecycle state of a session. Mirrors the `SessionState` enum in
+ * `macp/v1/envelope.proto`.
+ *
+ * `SESSION_STATE_SUSPENDED` is a non-terminal pause (TTL is banked while
+ * suspended and restored on resume); `SESSION_STATE_CANCELLED` is the terminal
+ * state for an explicit `CancelSession` — distinct from `SESSION_STATE_EXPIRED`
+ * (TTL / deterministic runtime policy) so consumers can tell explicit
+ * cancellation from expiry.
+ */
+export type SessionState = 'SESSION_STATE_UNSPECIFIED' | 'SESSION_STATE_OPEN' | 'SESSION_STATE_RESOLVED' | 'SESSION_STATE_EXPIRED' | 'SESSION_STATE_SUSPENDED' | 'SESSION_STATE_CANCELLED';
 export interface Ack {
     ok?: boolean;
     duplicate?: boolean;
     messageId?: string;
     sessionId?: string;
     acceptedAtUnixMs?: string;
-    sessionState?: string;
+    sessionState?: SessionState;
     error?: MacpErrorShape;
 }
 export interface ParticipantActivity {
@@ -36,7 +47,7 @@ export interface ParticipantActivity {
 export interface SessionMetadata {
     sessionId?: string;
     mode?: string;
-    state?: string;
+    state?: SessionState;
     startedAtUnixMs?: string;
     expiresAtUnixMs?: string;
     modeVersion?: string;
@@ -99,6 +110,15 @@ export interface SessionStartPayload {
     extensions?: Record<string, Buffer>;
     roots?: Root[];
 }
+/**
+ * Reference to a specific accepted commitment, used for cross-session
+ * supersession (RFC-MACP-0001 §7.3). Mirrors `macp.v1.CommitmentRef`.
+ */
+export interface CommitmentRef {
+    sessionId: string;
+    /** Content hash of the superseded `CommitmentPayload`. */
+    commitmentHash: string;
+}
 export interface CommitmentPayload {
     commitmentId: string;
     action: string;
@@ -108,6 +128,13 @@ export interface CommitmentPayload {
     policyVersion?: string;
     configurationVersion: string;
     outcomePositive?: boolean;
+    /**
+     * Cross-session supersession (RFC-MACP-0001 §7.3): when present, this
+     * commitment supersedes a prior commitment identified by
+     * `{sessionId, commitmentHash}`. The superseding commitment lives in a NEW
+     * session — a RESOLVED session accepts no further messages.
+     */
+    supersedes?: CommitmentRef;
 }
 export interface SignalPayload {
     signalType: string;
@@ -264,7 +291,7 @@ export interface RegistryChanged {
 export interface RootsChanged {
     observedAtUnixMs: string;
 }
-export type SessionLifecycleEventType = 'EVENT_TYPE_UNSPECIFIED' | 'EVENT_TYPE_CREATED' | 'EVENT_TYPE_RESOLVED' | 'EVENT_TYPE_EXPIRED';
+export type SessionLifecycleEventType = 'EVENT_TYPE_UNSPECIFIED' | 'EVENT_TYPE_CREATED' | 'EVENT_TYPE_RESOLVED' | 'EVENT_TYPE_EXPIRED' | 'EVENT_TYPE_SUSPENDED' | 'EVENT_TYPE_RESUMED' | 'EVENT_TYPE_CANCELLED';
 export interface SessionLifecycleEvent {
     eventType: SessionLifecycleEventType;
     session: SessionMetadata;

package/dist/watchers.d.ts

@@ -1,6 +1,28 @@
 import type { AuthConfig } from './auth';
 import type { MacpClient } from './client';
-import type { Envelope, PolicyDescriptor, RegistryChanged, RootsChanged, SessionLifecycleEvent } from './types';
+import type { Envelope, PolicyDescriptor, RegistryChanged, RootsChanged, SessionLifecycleEvent, SessionLifecycleEventType } from './types';
+/**
+ * The lifecycle event types after which a session emits no further events.
+ * `EVENT_TYPE_CANCELLED` (proto 0.1.3) is terminal alongside `RESOLVED` and
+ * `EXPIRED`; `SUSPENDED` / `RESUMED` are non-terminal. Parity with python-sdk
+ * `SessionLifecycle.is_terminal`.
+ */
+export declare const TERMINAL_SESSION_LIFECYCLE_EVENT_TYPES: readonly SessionLifecycleEventType[];
+type LifecycleEventOrType = SessionLifecycleEvent | SessionLifecycleEventType;
+/**
+ * Predicates over a {@link SessionLifecycleEvent} (or a bare
+ * {@link SessionLifecycleEventType}), mirroring python-sdk's `SessionLifecycle`
+ * properties so consumers can classify lifecycle events without re-deriving the
+ * proto enum strings. {@link isTerminalSessionLifecycleEvent} deliberately
+ * includes `EVENT_TYPE_CANCELLED`.
+ */
+export declare const isSessionCreated: (e: LifecycleEventOrType) => boolean;
+export declare const isSessionResolved: (e: LifecycleEventOrType) => boolean;
+export declare const isSessionExpired: (e: LifecycleEventOrType) => boolean;
+export declare const isSessionCancelled: (e: LifecycleEventOrType) => boolean;
+export declare const isSessionSuspended: (e: LifecycleEventOrType) => boolean;
+export declare const isSessionResumed: (e: LifecycleEventOrType) => boolean;
+export declare const isTerminalSessionLifecycleEvent: (e: LifecycleEventOrType) => boolean;
 export declare class ModeRegistryWatcher {
     private readonly client;
     private readonly auth?;
@@ -48,10 +70,23 @@ export declare class PolicyWatcher {
 export declare class SessionLifecycleWatcher {
     private readonly client;
     private readonly auth?;
+    private deprecatedEventsWarned;
+    private deprecatedNextEventWarned;
     constructor(client: MacpClient, options?: {
         auth?: AuthConfig;
     });
-    events(signal?: AbortSignal): AsyncGenerator<SessionLifecycleEvent, void, void>;
+    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>;
 }
+export {};

package/dist/watchers.js

@@ -1,6 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionLifecycleWatcher = exports.PolicyWatcher = exports.SignalWatcher = exports.RootsWatcher = exports.ModeRegistryWatcher = void 0;
+exports.SessionLifecycleWatcher = exports.PolicyWatcher = exports.SignalWatcher = exports.RootsWatcher = exports.ModeRegistryWatcher = exports.isTerminalSessionLifecycleEvent = exports.isSessionResumed = exports.isSessionSuspended = exports.isSessionCancelled = exports.isSessionExpired = exports.isSessionResolved = exports.isSessionCreated = exports.TERMINAL_SESSION_LIFECYCLE_EVENT_TYPES = void 0;
+const logging_1 = require("./logging");
+/**
+ * The lifecycle event types after which a session emits no further events.
+ * `EVENT_TYPE_CANCELLED` (proto 0.1.3) is terminal alongside `RESOLVED` and
+ * `EXPIRED`; `SUSPENDED` / `RESUMED` are non-terminal. Parity with python-sdk
+ * `SessionLifecycle.is_terminal`.
+ */
+exports.TERMINAL_SESSION_LIFECYCLE_EVENT_TYPES = [
+    'EVENT_TYPE_RESOLVED',
+    'EVENT_TYPE_EXPIRED',
+    'EVENT_TYPE_CANCELLED',
+];
+function lifecycleEventType(e) {
+    return typeof e === 'string' ? e : e.eventType;
+}
+/**
+ * Predicates over a {@link SessionLifecycleEvent} (or a bare
+ * {@link SessionLifecycleEventType}), mirroring python-sdk's `SessionLifecycle`
+ * properties so consumers can classify lifecycle events without re-deriving the
+ * proto enum strings. {@link isTerminalSessionLifecycleEvent} deliberately
+ * includes `EVENT_TYPE_CANCELLED`.
+ */
+const isSessionCreated = (e) => lifecycleEventType(e) === 'EVENT_TYPE_CREATED';
+exports.isSessionCreated = isSessionCreated;
+const isSessionResolved = (e) => lifecycleEventType(e) === 'EVENT_TYPE_RESOLVED';
+exports.isSessionResolved = isSessionResolved;
+const isSessionExpired = (e) => lifecycleEventType(e) === 'EVENT_TYPE_EXPIRED';
+exports.isSessionExpired = isSessionExpired;
+const isSessionCancelled = (e) => lifecycleEventType(e) === 'EVENT_TYPE_CANCELLED';
+exports.isSessionCancelled = isSessionCancelled;
+const isSessionSuspended = (e) => lifecycleEventType(e) === 'EVENT_TYPE_SUSPENDED';
+exports.isSessionSuspended = isSessionSuspended;
+const isSessionResumed = (e) => lifecycleEventType(e) === 'EVENT_TYPE_RESUMED';
+exports.isSessionResumed = isSessionResumed;
+const isTerminalSessionLifecycleEvent = (e) => exports.TERMINAL_SESSION_LIFECYCLE_EVENT_TYPES.includes(lifecycleEventType(e));
+exports.isTerminalSessionLifecycleEvent = isTerminalSessionLifecycleEvent;
 function serverStreamToAsyncGenerator(stream) {
     const queue = [];
     let resolve = null;
@@ -177,11 +213,13 @@ exports.PolicyWatcher = PolicyWatcher;
 class SessionLifecycleWatcher {
     client;
     auth;
+    deprecatedEventsWarned = false;
+    deprecatedNextEventWarned = false;
     constructor(client, options) {
         this.client = client;
         this.auth = options?.auth;
     }
-    async *events(signal) {
+    async *changes(signal) {
         const stream = this.client.watchSessions(this.auth);
         if (signal) {
             signal.addEventListener('abort', () => stream.cancel(), { once: true });
@@ -193,17 +231,39 @@ class SessionLifecycleWatcher {
         }
     }
     async watch(handler) {
-        for await (const event of this.events()) {
+        for await (const event of this.changes()) {
             await handler(event);
         }
     }
-    async nextEvent() {
-        const gen = this.events();
+    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.2",
+  "version": "0.4.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.1",
+    "@multiagentcoordinationprotocol/proto": "^0.1.3",
     "protobufjs": "^8.0.0"
   },
   "devDependencies": {