@robota-sdk/agent-session 3.0.7 → 3.1.1

package/dist/session-claims-DELiAZkZ.d.cts

@@ -0,0 +1,145 @@
+import { TProcessOwnerLiveness } from "@robota-sdk/agent-core";
+import { ISessionClaim, TSessionLoadOutcome } from "@robota-sdk/agent-interface-session";
+//#region src/session-log-reference-types.d.ts
+/**
+ * Leaf type module for {@link IExternalPayloadReference}.
+ *
+ * Split out of `session-logger.ts` so `session-log-sinks.ts` and `session-log-payload.ts` can
+ * depend on this type without importing back from `session-logger.ts`, which previously created
+ * import cycles among the three files.
+ */
+interface IExternalPayloadReference {
+  kind: 'external-payload';
+  encoding: 'json';
+  sha256: string;
+  byteLength: number;
+  relativePath: string;
+}
+/** Session log event data — extensible record of event metadata. */
+type TSessionLogValue = string | number | boolean | object | null | undefined;
+type TSessionLogData = Record<string, TSessionLogValue>;
+/**
+ * Hands a host the function that writes out everything still buffered, to run when the process is
+ * about to end (see `registerProcessExitFlush` in `@robota-sdk/agent-session/node`).
+ */
+type TRegisterExitFlush = (flush: () => void) => void;
+interface IFileSessionLoggerOptions {
+  externalPayloadThresholdBytes?: number;
+  redactedValue?: string;
+  /**
+   * Called once per distinct function (not once per logger) with a function that flushes every live
+   * logger, so a stream's buffered tail still reaches the log when the process exits mid-stream.
+   * Pass the same function to every logger. Absent, nothing is flushed on exit: the log then misses
+   * the unflushed tail of an abnormal exit.
+   */
+  registerExitFlush?: TRegisterExitFlush;
+}
+//#endregion
+//#region src/session-log-sinks.d.ts
+/** Canonical validation and construction for every session-log external-payload reference. */
+declare function createSessionLogExternalPayloadReference(sessionId: string, sha256: string, serialized: string): IExternalPayloadReference;
+/** Workspace-neutral sink for content-addressed external JSON payloads. */
+interface IExternalPayloadSink {
+  writeJson(sessionId: string, sha256: string, serialized: string): IExternalPayloadReference;
+}
+/** Workspace-neutral append sink for session-log bytes. */
+interface ISessionLogSink {
+  append(sessionId: string, text: string): void;
+  readonly externalPayloadSink?: IExternalPayloadSink;
+}
+//#endregion
+//#region src/external-payload-source-types.d.ts
+/**
+ * Leaf type module for {@link IExternalPayloadSource} and {@link ISessionLogSource}.
+ *
+ * Split out of `session-log-sources.ts` so `external-payload-resolution-contracts.ts` can depend
+ * on {@link IExternalPayloadSource} without importing back from `session-log-sources.ts`, which
+ * previously created an import cycle between the two.
+ */
+/** Workspace-neutral byte source for relative external-payload references. */
+interface IExternalPayloadSource {
+  readBytes(relativePath: string, maxBytes: number): Uint8Array | undefined;
+}
+/** Workspace-neutral source for one session-log document and its optional payload source. */
+interface ISessionLogSource {
+  /**
+   * The log's text as a plain store would hold it, or `undefined` when there is no log. A source
+   * that seals opens each sealed line, and fails on the first one it cannot: `ArtifactLockedError`
+   * while the keys are locked, `ArtifactCorruptError` for a line that does not open, and
+   * `SessionLogDecodeError` (`UNSUPPORTED_VERSION`) for one a newer build sealed. A plain source
+   * meeting a sealed line throws `ArtifactLockedError` with the reason `no-keys`, since no key in
+   * its process opens it.
+   */
+  readText(): string | undefined;
+  readonly externalPayloadSource?: IExternalPayloadSource;
+}
+//#endregion
+//#region src/session-claims.d.ts
+/** Why a claim, a lend or a write was refused. */
+type TSessionClaimRefusal =
+/**
+ * Another writer holds the id: a session of this or another store instance, a process it is lent
+ * to, or another process. The refusal names who, as far as it can tell.
+ */
+'has_writer' |
+/**
+ * What it was done under has ended: a save under a claim that is not the id's live one (it ended,
+ * it is another id's, or its marker is no longer its own), or a claim under a lease that ended.
+ */
+'released';
+/** Who holds a session's writer marker, as a refusal names it. */
+interface ISessionWriterHolder {
+  readonly pid?: number;
+  readonly hostname?: string;
+  /** The holder's start time, where the platform reads one. */
+  readonly startTime?: string;
+  /** This process holds it: a session of this store running or closing here, or a lend not yet taken over. */
+  readonly self: boolean;
+  readonly liveness: TProcessOwnerLiveness;
+  /** The id is lent: the holder is the subagent this process started, or this process until it takes over. */
+  readonly lent?: true;
+}
+/** How a store words its refusals: the command that releases a marker whose holder is not running. */
+interface ISessionClaimRefusalWords {
+  readonly releaseCommand?: (sessionId: string) => string;
+}
+/**
+ * The process a store runs in, as a refusal names it: the Node store states it, because this module
+ * is neutral and reads no process. A refusal from a store with none names no pid and adds no
+ * platform sentence.
+ */
+interface ISessionClaimProcess {
+  readonly pid: number;
+  /** Windows reads no start time, so a holder that crashed may still be shown as holding the id. */
+  readonly windows: boolean;
+}
+/** What a refusal carries beside its reason. */
+interface ISessionClaimRefusalDetails extends ISessionClaimRefusalWords {
+  readonly holder?: ISessionWriterHolder;
+  /** A `released` refusal of a claim under a lease, not of a save. */
+  readonly lease?: true;
+  /** The process the refusing store runs in. */
+  readonly ownProcess?: ISessionClaimProcess;
+}
+/** A claim, a lend or a write the store refused. Fixed text, the session id and the holder only. */
+declare class SessionClaimedError extends Error {
+  readonly code: "SESSION_CLAIMED";
+  readonly sessionId: string;
+  readonly reason: TSessionClaimRefusal;
+  /** Who holds the id, for a `has_writer` refusal. */
+  readonly holder: ISessionWriterHolder | undefined;
+  /**
+   * A session of this process holds the id and has not let its claim go, so a caller may try again
+   * once it has. Not so for a lend, which runs until its subagent has exited, nor for another process.
+   */
+  readonly closing: boolean;
+  constructor(sessionId: string, reason: TSessionClaimRefusal, details?: ISessionClaimRefusalDetails);
+}
+/**
+ * Whether `error` is a {@link SessionClaimedError}, by `code`: this package ships an ES and a CommonJS
+ * build, and the framework and a host that load one each see two classes no `instanceof` matches across.
+ */
+declare function isSessionClaimedError(error: unknown): error is SessionClaimedError;
+//#endregion
+export { isSessionClaimedError as a, IExternalPayloadSink as c, IExternalPayloadReference as d, IFileSessionLoggerOptions as f, TSessionClaimRefusal as i, ISessionLogSink as l, TSessionLogValue as m, ISessionWriterHolder as n, IExternalPayloadSource as o, TSessionLogData as p, SessionClaimedError as r, ISessionLogSource as s, ISessionClaimRefusalWords as t, createSessionLogExternalPayloadReference as u };
+//# sourceMappingURL=session-claims-DELiAZkZ.d.cts.map

package/dist/session-claims-DELiAZkZ.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-claims-DELiAZkZ.d.cts","names":[],"sources":["../src/session-log-reference-types.ts","../src/session-log-sinks.ts","../src/external-payload-source-types.ts","../src/session-claims.ts"],"mappings":";;;;;;;;;;UAOiB;EACf;EACA;EACA;EACA;EACA;;;KAIU;KACA,kBAAkB,eAAe;;;;;KAMjC,sBAAsB;UAEjB;EACf;EACA;;;;;;;EAOA,oBAAoB;;;;;iBClBN,yCACd,mBACA,gBACA,qBACC;;UAcc;EACf,UAAU,mBAAmB,gBAAgB,qBAAqB;;;UAInD;EACf,OAAO,mBAAmB;WACjB,sBAAsB;;;;;;;;;;;;UChChB;EACf,UAAU,sBAAsB,mBAAmB;;;UAIpC;;;;;;;;;EASf;WACS,wBAAwB;;;;;KCAvB;;;;;;;;;;;;UAaK;WACN;WACA;;WAEA;;WAEA;WACA,UAAU;;WAEV;;;UAIM;WACN,kBAAkB;;;;;;;UAQZ;WACN;;WAEA;;;UAIM,oCAAoC;WAC1C,SAAS;;WAET;;WAEA,aAAa;;;cAsFX,4BAA4B;WAC9B;WACA;WACA,QAAQ;;WAER,QAAQ;;;;;WAKR;EAGP,YAAA,mBACA,QAAQ,sBACR,UAAS;;;;;;iBAkBG,sBAAsB,iBAAiB,SAAS"}

package/dist/session-claims-DELiAZkZ.d.ts

@@ -0,0 +1,145 @@
+import { TProcessOwnerLiveness } from "@robota-sdk/agent-core";
+import { ISessionClaim, TSessionLoadOutcome } from "@robota-sdk/agent-interface-session";
+//#region src/session-log-reference-types.d.ts
+/**
+ * Leaf type module for {@link IExternalPayloadReference}.
+ *
+ * Split out of `session-logger.ts` so `session-log-sinks.ts` and `session-log-payload.ts` can
+ * depend on this type without importing back from `session-logger.ts`, which previously created
+ * import cycles among the three files.
+ */
+interface IExternalPayloadReference {
+  kind: 'external-payload';
+  encoding: 'json';
+  sha256: string;
+  byteLength: number;
+  relativePath: string;
+}
+/** Session log event data — extensible record of event metadata. */
+type TSessionLogValue = string | number | boolean | object | null | undefined;
+type TSessionLogData = Record<string, TSessionLogValue>;
+/**
+ * Hands a host the function that writes out everything still buffered, to run when the process is
+ * about to end (see `registerProcessExitFlush` in `@robota-sdk/agent-session/node`).
+ */
+type TRegisterExitFlush = (flush: () => void) => void;
+interface IFileSessionLoggerOptions {
+  externalPayloadThresholdBytes?: number;
+  redactedValue?: string;
+  /**
+   * Called once per distinct function (not once per logger) with a function that flushes every live
+   * logger, so a stream's buffered tail still reaches the log when the process exits mid-stream.
+   * Pass the same function to every logger. Absent, nothing is flushed on exit: the log then misses
+   * the unflushed tail of an abnormal exit.
+   */
+  registerExitFlush?: TRegisterExitFlush;
+}
+//#endregion
+//#region src/session-log-sinks.d.ts
+/** Canonical validation and construction for every session-log external-payload reference. */
+declare function createSessionLogExternalPayloadReference(sessionId: string, sha256: string, serialized: string): IExternalPayloadReference;
+/** Workspace-neutral sink for content-addressed external JSON payloads. */
+interface IExternalPayloadSink {
+  writeJson(sessionId: string, sha256: string, serialized: string): IExternalPayloadReference;
+}
+/** Workspace-neutral append sink for session-log bytes. */
+interface ISessionLogSink {
+  append(sessionId: string, text: string): void;
+  readonly externalPayloadSink?: IExternalPayloadSink;
+}
+//#endregion
+//#region src/external-payload-source-types.d.ts
+/**
+ * Leaf type module for {@link IExternalPayloadSource} and {@link ISessionLogSource}.
+ *
+ * Split out of `session-log-sources.ts` so `external-payload-resolution-contracts.ts` can depend
+ * on {@link IExternalPayloadSource} without importing back from `session-log-sources.ts`, which
+ * previously created an import cycle between the two.
+ */
+/** Workspace-neutral byte source for relative external-payload references. */
+interface IExternalPayloadSource {
+  readBytes(relativePath: string, maxBytes: number): Uint8Array | undefined;
+}
+/** Workspace-neutral source for one session-log document and its optional payload source. */
+interface ISessionLogSource {
+  /**
+   * The log's text as a plain store would hold it, or `undefined` when there is no log. A source
+   * that seals opens each sealed line, and fails on the first one it cannot: `ArtifactLockedError`
+   * while the keys are locked, `ArtifactCorruptError` for a line that does not open, and
+   * `SessionLogDecodeError` (`UNSUPPORTED_VERSION`) for one a newer build sealed. A plain source
+   * meeting a sealed line throws `ArtifactLockedError` with the reason `no-keys`, since no key in
+   * its process opens it.
+   */
+  readText(): string | undefined;
+  readonly externalPayloadSource?: IExternalPayloadSource;
+}
+//#endregion
+//#region src/session-claims.d.ts
+/** Why a claim, a lend or a write was refused. */
+type TSessionClaimRefusal =
+/**
+ * Another writer holds the id: a session of this or another store instance, a process it is lent
+ * to, or another process. The refusal names who, as far as it can tell.
+ */
+'has_writer' |
+/**
+ * What it was done under has ended: a save under a claim that is not the id's live one (it ended,
+ * it is another id's, or its marker is no longer its own), or a claim under a lease that ended.
+ */
+'released';
+/** Who holds a session's writer marker, as a refusal names it. */
+interface ISessionWriterHolder {
+  readonly pid?: number;
+  readonly hostname?: string;
+  /** The holder's start time, where the platform reads one. */
+  readonly startTime?: string;
+  /** This process holds it: a session of this store running or closing here, or a lend not yet taken over. */
+  readonly self: boolean;
+  readonly liveness: TProcessOwnerLiveness;
+  /** The id is lent: the holder is the subagent this process started, or this process until it takes over. */
+  readonly lent?: true;
+}
+/** How a store words its refusals: the command that releases a marker whose holder is not running. */
+interface ISessionClaimRefusalWords {
+  readonly releaseCommand?: (sessionId: string) => string;
+}
+/**
+ * The process a store runs in, as a refusal names it: the Node store states it, because this module
+ * is neutral and reads no process. A refusal from a store with none names no pid and adds no
+ * platform sentence.
+ */
+interface ISessionClaimProcess {
+  readonly pid: number;
+  /** Windows reads no start time, so a holder that crashed may still be shown as holding the id. */
+  readonly windows: boolean;
+}
+/** What a refusal carries beside its reason. */
+interface ISessionClaimRefusalDetails extends ISessionClaimRefusalWords {
+  readonly holder?: ISessionWriterHolder;
+  /** A `released` refusal of a claim under a lease, not of a save. */
+  readonly lease?: true;
+  /** The process the refusing store runs in. */
+  readonly ownProcess?: ISessionClaimProcess;
+}
+/** A claim, a lend or a write the store refused. Fixed text, the session id and the holder only. */
+declare class SessionClaimedError extends Error {
+  readonly code: "SESSION_CLAIMED";
+  readonly sessionId: string;
+  readonly reason: TSessionClaimRefusal;
+  /** Who holds the id, for a `has_writer` refusal. */
+  readonly holder: ISessionWriterHolder | undefined;
+  /**
+   * A session of this process holds the id and has not let its claim go, so a caller may try again
+   * once it has. Not so for a lend, which runs until its subagent has exited, nor for another process.
+   */
+  readonly closing: boolean;
+  constructor(sessionId: string, reason: TSessionClaimRefusal, details?: ISessionClaimRefusalDetails);
+}
+/**
+ * Whether `error` is a {@link SessionClaimedError}, by `code`: this package ships an ES and a CommonJS
+ * build, and the framework and a host that load one each see two classes no `instanceof` matches across.
+ */
+declare function isSessionClaimedError(error: unknown): error is SessionClaimedError;
+//#endregion
+export { isSessionClaimedError as a, IExternalPayloadSink as c, IExternalPayloadReference as d, IFileSessionLoggerOptions as f, TSessionClaimRefusal as i, ISessionLogSink as l, TSessionLogValue as m, ISessionWriterHolder as n, IExternalPayloadSource as o, TSessionLogData as p, SessionClaimedError as r, ISessionLogSource as s, ISessionClaimRefusalWords as t, createSessionLogExternalPayloadReference as u };
+//# sourceMappingURL=session-claims-DELiAZkZ.d.ts.map

package/dist/session-claims-DELiAZkZ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-claims-DELiAZkZ.d.ts","names":[],"sources":["../src/session-log-reference-types.ts","../src/session-log-sinks.ts","../src/external-payload-source-types.ts","../src/session-claims.ts"],"mappings":";;;;;;;;;;UAOiB;EACf;EACA;EACA;EACA;EACA;;;KAIU;KACA,kBAAkB,eAAe;;;;;KAMjC,sBAAsB;UAEjB;EACf;EACA;;;;;;;EAOA,oBAAoB;;;;;iBClBN,yCACd,mBACA,gBACA,qBACC;;UAcc;EACf,UAAU,mBAAmB,gBAAgB,qBAAqB;;;UAInD;EACf,OAAO,mBAAmB;WACjB,sBAAsB;;;;;;;;;;;;UChChB;EACf,UAAU,sBAAsB,mBAAmB;;;UAIpC;;;;;;;;;EASf;WACS,wBAAwB;;;;;KCAvB;;;;;;;;;;;;UAaK;WACN;WACA;;WAEA;;WAEA;WACA,UAAU;;WAEV;;;UAIM;WACN,kBAAkB;;;;;;;UAQZ;WACN;;WAEA;;;UAIM,oCAAoC;WAC1C,SAAS;;WAET;;WAEA,aAAa;;;cAsFX,4BAA4B;WAC9B;WACA;WACA,QAAQ;;WAER,QAAQ;;;;;WAKR;EAGP,YAAA,mBACA,QAAQ,sBACR,UAAS;;;;;;iBAkBG,sBAAsB,iBAAiB,SAAS"}

package/package.json

@@ -1,32 +1,32 @@
 {
   "name": "@robota-sdk/agent-session",
-  "version": "3.0.7",
+  "version": "3.1.1",
   "description": "Session for the Robota SDK: permission-gated tool execution, hooks, context tracking, compaction and persistence",
   "type": "module",
-  "main": "dist/node/index.js",
-  "types": "dist/node/index.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "source": "./src/index.ts",
-      "node": {
-        "import": {
-          "types": "./dist/node/index.d.ts",
-          "default": "./dist/node/index.js"
-        },
-        "require": {
-          "types": "./dist/node/index.d.cts",
-          "default": "./dist/node/index.cjs"
-        }
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
       },
-      "default": {
-        "import": {
-          "types": "./dist/node/index.d.ts",
-          "default": "./dist/node/index.js"
-        },
-        "require": {
-          "types": "./dist/node/index.d.cts",
-          "default": "./dist/node/index.cjs"
-        }
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./node": {
+      "source": "./src/node.ts",
+      "browser": null,
+      "import": {
+        "types": "./dist/node.d.ts",
+        "default": "./dist/node.js"
+      },
+      "require": {
+        "types": "./dist/node.d.cts",
+        "default": "./dist/node.cjs"
       }
     },
     "./package.json": "./package.json"
@@ -63,10 +63,11 @@
     "node": ">=22.12.0"
   },
   "dependencies": {
-    "@robota-sdk/agent-core": "3.0.7",
-    "@robota-sdk/agent-file-authority": "3.0.7",
-    "@robota-sdk/agent-interface-execution": "3.0.7",
-    "@robota-sdk/agent-interface-session": "3.0.7"
+    "koffi": "3.3.1",
+    "@robota-sdk/agent-core": "3.1.1",
+    "@robota-sdk/agent-file-authority": "3.1.1",
+    "@robota-sdk/agent-interface-execution": "3.1.1",
+    "@robota-sdk/agent-interface-session": "3.1.1"
   },
   "devDependencies": {
     "eslint": "^8.57.1",