@sapiom/agent - npm Package Compare versions

Comparing version 0.11.0 to 0.12.0

dist/cjs/ctx-shared-serialization.d.ts

+import { z } from 'zod/v4';
+import type { CtxSharedSizeLimitPhase } from './ctx-shared-quota.js';
+import { AgentError } from './errors.js';
+export declare const CTX_SHARED_SERIALIZATION_ERROR_CONTRACT: Readonly<{
+    readonly version: 1;
+    readonly errorCode: "CTX_SHARED_SERIALIZATION_FAILED";
+    readonly retryable: false;
+}>;
+export type CtxSharedSerializationPhase = CtxSharedSizeLimitPhase;
+export declare const ctxSharedSerializationErrorPayloadSchema: z.ZodObject<{
+    name: z.ZodLiteral<"CtxSharedSerializationError">;
+    message: z.ZodString;
+    code: z.ZodLiteral<"CTX_SHARED_SERIALIZATION_FAILED">;
+    version: z.ZodNumber;
+    stepName: z.ZodString;
+    phase: z.ZodString;
+    retryable: z.ZodLiteral<false>;
+    stack: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CtxSharedSerializationErrorPayload = z.infer<typeof ctxSharedSerializationErrorPayloadSchema>;
+export interface CtxSharedSerializationErrorOptions {
+    readonly stepName: string;
+    readonly phase: CtxSharedSerializationPhase;
+    readonly stack?: string;
+}
+export declare class CtxSharedSerializationError extends AgentError {
+    readonly code: "CTX_SHARED_SERIALIZATION_FAILED";
+    readonly version: 1;
+    readonly stepName: string;
+    readonly phase: CtxSharedSerializationPhase;
+    readonly retryable: false;
+    constructor(options: CtxSharedSerializationErrorOptions);
+    toJSON(): CtxSharedSerializationErrorPayload;
+}
+export declare function isCtxSharedSerializationErrorPayload(value: unknown): value is CtxSharedSerializationErrorPayload;

dist/cjs/ctx-shared-serialization.js

+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CtxSharedSerializationError = exports.ctxSharedSerializationErrorPayloadSchema = exports.CTX_SHARED_SERIALIZATION_ERROR_CONTRACT = void 0;
+exports.isCtxSharedSerializationErrorPayload = isCtxSharedSerializationErrorPayload;
+const v4_1 = require("zod/v4");
+const errors_js_1 = require("./errors.js");
+exports.CTX_SHARED_SERIALIZATION_ERROR_CONTRACT = Object.freeze({
+    version: 1,
+    errorCode: 'CTX_SHARED_SERIALIZATION_FAILED',
+    retryable: false,
+});
+exports.ctxSharedSerializationErrorPayloadSchema = v4_1.z.object({
+    name: v4_1.z.literal('CtxSharedSerializationError'),
+    message: v4_1.z.string(),
+    code: v4_1.z.literal(exports.CTX_SHARED_SERIALIZATION_ERROR_CONTRACT.errorCode),
+    version: v4_1.z.number().int().positive(),
+    stepName: v4_1.z.string().min(1),
+    phase: v4_1.z.string().min(1),
+    retryable: v4_1.z.literal(false),
+    stack: v4_1.z.string().optional(),
+});
+class CtxSharedSerializationError extends errors_js_1.AgentError {
+    constructor(options) {
+        super(`Step '${options.stepName}' could not serialize the ctx.shared snapshot during ${options.phase}. ` +
+            `ctx.shared uses compact JSON.stringify; remove circular references and BigInt values, and ensure ` +
+            `custom toJSON methods return normally.`);
+        this.code = exports.CTX_SHARED_SERIALIZATION_ERROR_CONTRACT.errorCode;
+        this.version = exports.CTX_SHARED_SERIALIZATION_ERROR_CONTRACT.version;
+        this.retryable = exports.CTX_SHARED_SERIALIZATION_ERROR_CONTRACT.retryable;
+        this.name = 'CtxSharedSerializationError';
+        this.stepName = options.stepName;
+        this.phase = options.phase;
+        if (options.stack !== undefined)
+            this.stack = options.stack;
+    }
+    toJSON() {
+        return {
+            name: 'CtxSharedSerializationError',
+            message: this.message,
+            code: this.code,
+            version: this.version,
+            stepName: this.stepName,
+            phase: this.phase,
+            retryable: this.retryable,
+            ...(this.stack === undefined ? {} : { stack: this.stack }),
+        };
+    }
+}
+exports.CtxSharedSerializationError = CtxSharedSerializationError;
+function isCtxSharedSerializationErrorPayload(value) {
+    return exports.ctxSharedSerializationErrorPayloadSchema.safeParse(value).success;
+}

dist/esm/ctx-shared-serialization.d.ts

+import { z } from 'zod/v4';
+import type { CtxSharedSizeLimitPhase } from './ctx-shared-quota.js';
+import { AgentError } from './errors.js';
+export declare const CTX_SHARED_SERIALIZATION_ERROR_CONTRACT: Readonly<{
+    readonly version: 1;
+    readonly errorCode: "CTX_SHARED_SERIALIZATION_FAILED";
+    readonly retryable: false;
+}>;
+export type CtxSharedSerializationPhase = CtxSharedSizeLimitPhase;
+export declare const ctxSharedSerializationErrorPayloadSchema: z.ZodObject<{
+    name: z.ZodLiteral<"CtxSharedSerializationError">;
+    message: z.ZodString;
+    code: z.ZodLiteral<"CTX_SHARED_SERIALIZATION_FAILED">;
+    version: z.ZodNumber;
+    stepName: z.ZodString;
+    phase: z.ZodString;
+    retryable: z.ZodLiteral<false>;
+    stack: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CtxSharedSerializationErrorPayload = z.infer<typeof ctxSharedSerializationErrorPayloadSchema>;
+export interface CtxSharedSerializationErrorOptions {
+    readonly stepName: string;
+    readonly phase: CtxSharedSerializationPhase;
+    readonly stack?: string;
+}
+export declare class CtxSharedSerializationError extends AgentError {
+    readonly code: "CTX_SHARED_SERIALIZATION_FAILED";
+    readonly version: 1;
+    readonly stepName: string;
+    readonly phase: CtxSharedSerializationPhase;
+    readonly retryable: false;
+    constructor(options: CtxSharedSerializationErrorOptions);
+    toJSON(): CtxSharedSerializationErrorPayload;
+}
+export declare function isCtxSharedSerializationErrorPayload(value: unknown): value is CtxSharedSerializationErrorPayload;

dist/esm/ctx-shared-serialization.js

+import { z } from 'zod/v4';
+import { AgentError } from './errors.js';
+export const CTX_SHARED_SERIALIZATION_ERROR_CONTRACT = Object.freeze({
+    version: 1,
+    errorCode: 'CTX_SHARED_SERIALIZATION_FAILED',
+    retryable: false,
+});
+export const ctxSharedSerializationErrorPayloadSchema = z.object({
+    name: z.literal('CtxSharedSerializationError'),
+    message: z.string(),
+    code: z.literal(CTX_SHARED_SERIALIZATION_ERROR_CONTRACT.errorCode),
+    version: z.number().int().positive(),
+    stepName: z.string().min(1),
+    phase: z.string().min(1),
+    retryable: z.literal(false),
+    stack: z.string().optional(),
+});
+export class CtxSharedSerializationError extends AgentError {
+    constructor(options) {
+        super(`Step '${options.stepName}' could not serialize the ctx.shared snapshot during ${options.phase}. ` +
+            `ctx.shared uses compact JSON.stringify; remove circular references and BigInt values, and ensure ` +
+            `custom toJSON methods return normally.`);
+        this.code = CTX_SHARED_SERIALIZATION_ERROR_CONTRACT.errorCode;
+        this.version = CTX_SHARED_SERIALIZATION_ERROR_CONTRACT.version;
+        this.retryable = CTX_SHARED_SERIALIZATION_ERROR_CONTRACT.retryable;
+        this.name = 'CtxSharedSerializationError';
+        this.stepName = options.stepName;
+        this.phase = options.phase;
+        if (options.stack !== undefined)
+            this.stack = options.stack;
+    }
+    toJSON() {
+        return {
+            name: 'CtxSharedSerializationError',
+            message: this.message,
+            code: this.code,
+            version: this.version,
+            stepName: this.stepName,
+            phase: this.phase,
+            retryable: this.retryable,
+            ...(this.stack === undefined ? {} : { stack: this.stack }),
+        };
+    }
+}
+export function isCtxSharedSerializationErrorPayload(value) {
+    return ctxSharedSerializationErrorPayloadSchema.safeParse(value).success;
+}

CHANGELOG.md

 # @sapiom/orchestration
 
+## 0.12.0
+
+### Minor Changes
+
+- 555475d: Make `ctx.shared.set()` on the SDK's `InMemoryContextStore` an atomic
+  whole-snapshot quota gate. `runLocal` now constructs this store with step
+  context; hosts that have not adopted this store version may enforce the contract
+  only at execution boundaries during rollout. The store measures the complete
+  candidate as compact JSON UTF-8 before committing it, so oversized writes throw
+  `CTX_SHARED_SIZE_LIMIT_EXCEEDED` and retain the previous state.
+
+  Publish the bounded `CTX_SHARED_SERIALIZATION_FAILED` terminal error contract
+  for circular references, BigInt values, throwing `toJSON` methods, and other
+  `JSON.stringify` failures. Completion serializers and runners recognize the
+  new code through the closed platform-error registry and fail the step on its
+  current attempt without retrying. Ordinary JSON omission and coercion semantics
+  remain unchanged.
+
+  **Breaking:** `InMemoryContextStore.set()` can now throw synchronously for an
+  oversized or unserializable candidate. Existing local agents that wrote such
+  state now fail non-retryably on attempt 0. Migrate bulk state to durable storage
+  and keep only compact, JSON-compatible values or references in `ctx.shared`. If
+  a store is seeded with legacy invalid state, replace an offending key with a
+  value small enough to bring the complete candidate within the quota;
+  `TypedContextStore` has no `delete()` operation.
+
 ## 0.11.0
@@ -4,0 +30,0 @@

dist/cjs/context.d.ts

@@ -28,2 +28,5 @@ import type { Sapiom } from '@sapiom/tools';
 }
+export interface InMemoryContextStoreOptions {
+    readonly stepName: string;
+}
 export interface StepExecutionRecord {
@@ -43,3 +46,4 @@ readonly stepName: string;
     private state;
-    constructor(initial?: Partial<TShared>);
+    private readonly stepName;
+    constructor(initial?: Partial<TShared>, options?: InMemoryContextStoreOptions);
     get<K extends keyof TShared>(key: K): TShared[K] | undefined;
@@ -46,0 +50,0 @@ set<K extends keyof TShared>(key: K, value: TShared[K]): void;

dist/cjs/context.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryContextStore = void 0;
+const ctx_shared_quota_js_1 = require("./ctx-shared-quota.js");
+const ctx_shared_serialization_js_1 = require("./ctx-shared-serialization.js");
 class InMemoryContextStore {
-    constructor(initial = {}) {
+    constructor(initial = {}, options) {
         this.state = { ...initial };
+        const stepName = options?.stepName;
+        this.stepName = typeof stepName === 'string' && stepName.trim().length > 0 ? stepName : '(unknown step)';
     }
@@ -12,3 +16,21 @@ get(key) {
     set(key, value) {
-        this.state[key] = value;
+        const candidate = { ...this.state, [key]: value };
+        let violation;
+        try {
+            violation = (0, ctx_shared_quota_js_1.findCtxSharedSizeViolation)(candidate);
+        }
+        catch {
+            throw new ctx_shared_serialization_js_1.CtxSharedSerializationError({
+                stepName: this.stepName,
+                phase: 'ctx_shared_set',
+            });
+        }
+        if (violation) {
+            throw new ctx_shared_quota_js_1.CtxSharedSizeLimitExceededError({
+                actualBytes: violation.actualBytes,
+                stepName: this.stepName,
+                phase: 'ctx_shared_set',
+            });
+        }
+        this.state = candidate;
     }
@@ -15,0 +37,0 @@ has(key) {

dist/cjs/index.d.ts

@@ -7,3 +7,3 @@ export { DIRECTIVE_KIND, isContinue, isRetry, isPause, isTerminate, isFail } from './directives.js';
 export type { Step, StepResult, StepDefinition, Allowed } from './step.js';
-export type { AgentExecutionContext, TypedContextStore, StepExecutionRecord, StepLogger, FinishedStepStatus, } from './context.js';
+export type { AgentExecutionContext, TypedContextStore, InMemoryContextStoreOptions, StepExecutionRecord, StepLogger, FinishedStepStatus, } from './context.js';
 export { InMemoryContextStore } from './context.js';
@@ -16,2 +16,4 @@ export type { AgentDefinition } from './agent.js';
 export type { CtxSharedSizeLimitExceededErrorOptions, CtxSharedSizeLimitExceededPayload, CtxSharedSizeLimitPhase, CtxSharedSizeViolation, } from './ctx-shared-quota.js';
+export { CTX_SHARED_SERIALIZATION_ERROR_CONTRACT, CtxSharedSerializationError, ctxSharedSerializationErrorPayloadSchema, isCtxSharedSerializationErrorPayload, } from './ctx-shared-serialization.js';
+export type { CtxSharedSerializationErrorOptions, CtxSharedSerializationErrorPayload, CtxSharedSerializationPhase, } from './ctx-shared-serialization.js';
 export { isNonRetryableStepErrorPayload, parseNonRetryableStepErrorPayload } from './non-retryable-step-error.js';
@@ -18,0 +20,0 @@ export type { NonRetryableStepErrorPayload } from './non-retryable-step-error.js';

dist/cjs/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertValidGraph = exports.validateGraph = exports.buildManifest = exports.agentManifestSchema = exports.MANIFEST_PROTOCOL = exports.workflowInputContract = exports.stepInputContract = exports.exampleFromJsonSchema = exports.zodToJsonSchema = exports.resolveResourceHandle = exports.parseNonRetryableStepErrorPayload = exports.isNonRetryableStepErrorPayload = exports.measureCtxSharedSnapshotBytes = exports.isCtxSharedSizeLimitExceededPayload = exports.findCtxSharedSizeViolation = exports.ctxSharedSizeLimitExceededPayloadSchema = exports.CtxSharedSizeLimitExceededError = exports.MAX_SHARED_SNAPSHOT_BYTES = exports.CTX_SHARED_QUOTA_CONTRACT = exports.isStepInputValidationErrorPayload = exports.stepInputValidationErrorPayloadSchema = exports.STEP_INPUT_VALIDATION_ERROR_CONTRACT = exports.DisallowedTransitionError = exports.StepInputValidationError = exports.UnknownStepError = exports.AgentError = exports.LEGACY_ORCHESTRATION_DEFINITION_BRAND = exports.isLegacyOrchestrationDefinition = exports.AGENT_DEFINITION_BRAND = exports.isAgentDefinition = exports.defineAgent = exports.InMemoryContextStore = exports.defineStep = exports.retry = exports.pauseUntilSignal = exports.terminate = exports.goto = exports.isFail = exports.isTerminate = exports.isPause = exports.isRetry = exports.isContinue = exports.DIRECTIVE_KIND = void 0;
+exports.assertValidGraph = exports.validateGraph = exports.buildManifest = exports.agentManifestSchema = exports.MANIFEST_PROTOCOL = exports.workflowInputContract = exports.stepInputContract = exports.exampleFromJsonSchema = exports.zodToJsonSchema = exports.resolveResourceHandle = exports.parseNonRetryableStepErrorPayload = exports.isNonRetryableStepErrorPayload = exports.isCtxSharedSerializationErrorPayload = exports.ctxSharedSerializationErrorPayloadSchema = exports.CtxSharedSerializationError = exports.CTX_SHARED_SERIALIZATION_ERROR_CONTRACT = exports.measureCtxSharedSnapshotBytes = exports.isCtxSharedSizeLimitExceededPayload = exports.findCtxSharedSizeViolation = exports.ctxSharedSizeLimitExceededPayloadSchema = exports.CtxSharedSizeLimitExceededError = exports.MAX_SHARED_SNAPSHOT_BYTES = exports.CTX_SHARED_QUOTA_CONTRACT = exports.isStepInputValidationErrorPayload = exports.stepInputValidationErrorPayloadSchema = exports.STEP_INPUT_VALIDATION_ERROR_CONTRACT = exports.DisallowedTransitionError = exports.StepInputValidationError = exports.UnknownStepError = exports.AgentError = exports.LEGACY_ORCHESTRATION_DEFINITION_BRAND = exports.isLegacyOrchestrationDefinition = exports.AGENT_DEFINITION_BRAND = exports.isAgentDefinition = exports.defineAgent = exports.InMemoryContextStore = exports.defineStep = exports.retry = exports.pauseUntilSignal = exports.terminate = exports.goto = exports.isFail = exports.isTerminate = exports.isPause = exports.isRetry = exports.isContinue = exports.DIRECTIVE_KIND = void 0;
 var directives_js_1 = require("./directives.js");
@@ -43,2 +43,7 @@ Object.defineProperty(exports, "DIRECTIVE_KIND", { enumerable: true, get: function () { return directives_js_1.DIRECTIVE_KIND; } });
 Object.defineProperty(exports, "measureCtxSharedSnapshotBytes", { enumerable: true, get: function () { return ctx_shared_quota_js_1.measureCtxSharedSnapshotBytes; } });
+var ctx_shared_serialization_js_1 = require("./ctx-shared-serialization.js");
+Object.defineProperty(exports, "CTX_SHARED_SERIALIZATION_ERROR_CONTRACT", { enumerable: true, get: function () { return ctx_shared_serialization_js_1.CTX_SHARED_SERIALIZATION_ERROR_CONTRACT; } });
+Object.defineProperty(exports, "CtxSharedSerializationError", { enumerable: true, get: function () { return ctx_shared_serialization_js_1.CtxSharedSerializationError; } });
+Object.defineProperty(exports, "ctxSharedSerializationErrorPayloadSchema", { enumerable: true, get: function () { return ctx_shared_serialization_js_1.ctxSharedSerializationErrorPayloadSchema; } });
+Object.defineProperty(exports, "isCtxSharedSerializationErrorPayload", { enumerable: true, get: function () { return ctx_shared_serialization_js_1.isCtxSharedSerializationErrorPayload; } });
 var non_retryable_step_error_js_1 = require("./non-retryable-step-error.js");
@@ -45,0 +50,0 @@ Object.defineProperty(exports, "isNonRetryableStepErrorPayload", { enumerable: true, get: function () { return non_retryable_step_error_js_1.isNonRetryableStepErrorPayload; } });

dist/cjs/non-retryable-step-error.d.ts

 import { type CtxSharedSizeLimitExceededPayload } from './ctx-shared-quota.js';
+import { type CtxSharedSerializationErrorPayload } from './ctx-shared-serialization.js';
 import { type StepInputValidationErrorPayload } from './errors.js';
-export type NonRetryableStepErrorPayload = CtxSharedSizeLimitExceededPayload | StepInputValidationErrorPayload;
+export type NonRetryableStepErrorPayload = CtxSharedSizeLimitExceededPayload | StepInputValidationErrorPayload | CtxSharedSerializationErrorPayload;
 export declare function parseNonRetryableStepErrorPayload(value: unknown): NonRetryableStepErrorPayload | undefined;
 export declare function isNonRetryableStepErrorPayload(value: unknown): value is NonRetryableStepErrorPayload;

dist/cjs/non-retryable-step-error.js

@@ -6,2 +6,3 @@ "use strict";
 const ctx_shared_quota_js_1 = require("./ctx-shared-quota.js");
+const ctx_shared_serialization_js_1 = require("./ctx-shared-serialization.js");
 const errors_js_1 = require("./errors.js");
@@ -15,2 +16,5 @@ function parseNonRetryableStepErrorPayload(value) {
         return inputValidation.data;
+    const serialization = ctx_shared_serialization_js_1.ctxSharedSerializationErrorPayloadSchema.safeParse(value);
+    if (serialization.success)
+        return serialization.data;
     return undefined;
@@ -17,0 +21,0 @@ }

dist/esm/context.d.ts

@@ -28,2 +28,5 @@ import type { Sapiom } from '@sapiom/tools';
 }
+export interface InMemoryContextStoreOptions {
+    readonly stepName: string;
+}
 export interface StepExecutionRecord {
@@ -43,3 +46,4 @@ readonly stepName: string;
     private state;
-    constructor(initial?: Partial<TShared>);
+    private readonly stepName;
+    constructor(initial?: Partial<TShared>, options?: InMemoryContextStoreOptions);
     get<K extends keyof TShared>(key: K): TShared[K] | undefined;
@@ -46,0 +50,0 @@ set<K extends keyof TShared>(key: K, value: TShared[K]): void;

dist/esm/context.js

@@ -0,4 +1,8 @@
+import { CtxSharedSizeLimitExceededError, findCtxSharedSizeViolation } from './ctx-shared-quota.js';
+import { CtxSharedSerializationError } from './ctx-shared-serialization.js';
 export class InMemoryContextStore {
-    constructor(initial = {}) {
+    constructor(initial = {}, options) {
         this.state = { ...initial };
+        const stepName = options?.stepName;
+        this.stepName = typeof stepName === 'string' && stepName.trim().length > 0 ? stepName : '(unknown step)';
     }
@@ -9,3 +13,21 @@ get(key) {
     set(key, value) {
-        this.state[key] = value;
+        const candidate = { ...this.state, [key]: value };
+        let violation;
+        try {
+            violation = findCtxSharedSizeViolation(candidate);
+        }
+        catch {
+            throw new CtxSharedSerializationError({
+                stepName: this.stepName,
+                phase: 'ctx_shared_set',
+            });
+        }
+        if (violation) {
+            throw new CtxSharedSizeLimitExceededError({
+                actualBytes: violation.actualBytes,
+                stepName: this.stepName,
+                phase: 'ctx_shared_set',
+            });
+        }
+        this.state = candidate;
     }
@@ -12,0 +34,0 @@ has(key) {

dist/esm/index.d.ts

@@ -7,3 +7,3 @@ export { DIRECTIVE_KIND, isContinue, isRetry, isPause, isTerminate, isFail } from './directives.js';
 export type { Step, StepResult, StepDefinition, Allowed } from './step.js';
-export type { AgentExecutionContext, TypedContextStore, StepExecutionRecord, StepLogger, FinishedStepStatus, } from './context.js';
+export type { AgentExecutionContext, TypedContextStore, InMemoryContextStoreOptions, StepExecutionRecord, StepLogger, FinishedStepStatus, } from './context.js';
 export { InMemoryContextStore } from './context.js';
@@ -16,2 +16,4 @@ export type { AgentDefinition } from './agent.js';
 export type { CtxSharedSizeLimitExceededErrorOptions, CtxSharedSizeLimitExceededPayload, CtxSharedSizeLimitPhase, CtxSharedSizeViolation, } from './ctx-shared-quota.js';
+export { CTX_SHARED_SERIALIZATION_ERROR_CONTRACT, CtxSharedSerializationError, ctxSharedSerializationErrorPayloadSchema, isCtxSharedSerializationErrorPayload, } from './ctx-shared-serialization.js';
+export type { CtxSharedSerializationErrorOptions, CtxSharedSerializationErrorPayload, CtxSharedSerializationPhase, } from './ctx-shared-serialization.js';
 export { isNonRetryableStepErrorPayload, parseNonRetryableStepErrorPayload } from './non-retryable-step-error.js';
@@ -18,0 +20,0 @@ export type { NonRetryableStepErrorPayload } from './non-retryable-step-error.js';

dist/esm/index.js

@@ -8,2 +8,3 @@ export { DIRECTIVE_KIND, isContinue, isRetry, isPause, isTerminate, isFail } from './directives.js';
 export { CTX_SHARED_QUOTA_CONTRACT, MAX_SHARED_SNAPSHOT_BYTES, CtxSharedSizeLimitExceededError, ctxSharedSizeLimitExceededPayloadSchema, findCtxSharedSizeViolation, isCtxSharedSizeLimitExceededPayload, measureCtxSharedSnapshotBytes, } from './ctx-shared-quota.js';
+export { CTX_SHARED_SERIALIZATION_ERROR_CONTRACT, CtxSharedSerializationError, ctxSharedSerializationErrorPayloadSchema, isCtxSharedSerializationErrorPayload, } from './ctx-shared-serialization.js';
 export { isNonRetryableStepErrorPayload, parseNonRetryableStepErrorPayload } from './non-retryable-step-error.js';
@@ -10,0 +11,0 @@ export { resolveResourceHandle } from './config.js';

dist/esm/non-retryable-step-error.d.ts

 import { type CtxSharedSizeLimitExceededPayload } from './ctx-shared-quota.js';
+import { type CtxSharedSerializationErrorPayload } from './ctx-shared-serialization.js';
 import { type StepInputValidationErrorPayload } from './errors.js';
-export type NonRetryableStepErrorPayload = CtxSharedSizeLimitExceededPayload | StepInputValidationErrorPayload;
+export type NonRetryableStepErrorPayload = CtxSharedSizeLimitExceededPayload | StepInputValidationErrorPayload | CtxSharedSerializationErrorPayload;
 export declare function parseNonRetryableStepErrorPayload(value: unknown): NonRetryableStepErrorPayload | undefined;
 export declare function isNonRetryableStepErrorPayload(value: unknown): value is NonRetryableStepErrorPayload;

dist/esm/non-retryable-step-error.js

 import { ctxSharedSizeLimitExceededPayloadSchema } from './ctx-shared-quota.js';
+import { ctxSharedSerializationErrorPayloadSchema, } from './ctx-shared-serialization.js';
 import { stepInputValidationErrorPayloadSchema } from './errors.js';
@@ -10,2 +11,5 @@ export function parseNonRetryableStepErrorPayload(value) {
         return inputValidation.data;
+    const serialization = ctxSharedSerializationErrorPayloadSchema.safeParse(value);
+    if (serialization.success)
+        return serialization.data;
     return undefined;
@@ -12,0 +16,0 @@ }

package.json

 {
   "name": "@sapiom/agent",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Versioned public contract for authoring Sapiom agents: types, directive constructors/guards, defineAgent, defineStep, InMemoryContextStore. Shared by customer agent definitions, the sandbox step-runner, and the engine.",
@@ -5,0 +5,0 @@ "license": "MIT",

README.md

@@ -96,14 +96,25 @@ # @sapiom/agent
 
-This package publishes the quota contract and its measurement helpers; it does
-not make `ctx.shared.set()` a synchronous size gate by itself. Hosts enforce the
-contract at execution boundaries, and older hosts may temporarily enforce a
-smaller legacy limit during rollout.
+The SDK's `InMemoryContextStore.set()` synchronously measures the complete
+candidate snapshot before committing it. An oversized or unserializable
+candidate throws and leaves the previous snapshot unchanged. Hosts gain this
+setter-time gate when they construct this store version; hosts that have not
+adopted it may enforce the contract only at execution boundaries during rollout.
 
+Measurement follows `JSON.stringify` rather than a stricter JSON-value
+validator: values JSON normally omits or coerces retain those semantics, while
+circular references, BigInt values, and throwing `toJSON` methods are rejected.
+
 Keep small scalars, IDs, and durable-storage references in `ctx.shared`. Put
 bulk API responses, documents, research results, and other large state in
 durable storage, then carry only the resulting ID or reference. The stable
-machine code when an enforcing host rejects an oversized candidate is
-`CTX_SHARED_SIZE_LIMIT_EXCEEDED`; use its structured byte counts rather than
-parsing the human-readable message.
+machine code for an oversized candidate is `CTX_SHARED_SIZE_LIMIT_EXCEEDED`;
+JSON encoding failures use `CTX_SHARED_SERIALIZATION_FAILED`. Use the exported
+structural guards and structured fields rather than parsing messages or relying
+on `instanceof`: the host runner and an authored definition may carry separate
+inlined SDK copies.
 
+`TypedContextStore` has no `delete()` operation. To recover from legacy invalid
+state, replace an offending key with a compact, JSON-compatible value small
+enough to bring the complete candidate within the quota.
+
 ## Pausing on a long-running capability
@@ -110,0 +121,0 @@

No alert changes

Improved metrics

Total package byte prevSize

243638

6.59%

Number of package files

59

7.27%

Lines of code

2369

11.38%

Number of lines in readme file

191

6.11%

No dependency changes