@sapiom/agent-core - npm Package Compare versions

Comparing version 0.11.3 to 0.11.4

CHANGELOG.md

 # @sapiom/orchestration-core
 
+## 0.11.4
+
+### Patch Changes
+
+- af764cd: Publish the authoritative 256 KiB `ctx.shared` whole-snapshot contract from
+  `@sapiom/agent`: `CTX_SHARED_QUOTA_CONTRACT`,
+  `MAX_SHARED_SNAPSHOT_BYTES`, `measureCtxSharedSnapshotBytes`,
+  `findCtxSharedSizeViolation`, `CtxSharedSizeLimitExceededError`,
+  `ctxSharedSizeLimitExceededPayloadSchema`, and
+  `isCtxSharedSizeLimitExceededPayload`, plus the
+  `CtxSharedSizeLimitPhase`, `CtxSharedSizeViolation`,
+  `CtxSharedSizeLimitExceededPayload`, and
+  `CtxSharedSizeLimitExceededErrorOptions` types.
+
+  `@sapiom/agent-runtime` now publicly exports `stepCompletionErrorSchema`,
+  preserves compatible structured quota payloads through protocol-1 parsing, and
+  re-exports the canonical compatibility limit.
+
+  Structured quota payloads include the reporting contract `version` and retain
+  unknown non-empty future phases during mixed-version rollouts; current error
+  construction remains limited to the three published enforcement phases.
+
+  This release defines measurement and error contracts; it does not make
+  `ctx.shared.set()` an atomic size gate or add local/final host-boundary
+  enforcement by itself. Host versions must adopt the contract. Authoring skills,
+  scaffolds, and MCP guidance now document compact ID/reference usage and that
+  enforcement can vary during rollout.
+
+- Updated dependencies [af764cd]
+  - @sapiom/agent@0.10.0
+  - @sapiom/agent-runtime@0.5.0
+
 ## 0.11.3
@@ -4,0 +36,0 @@

dist/cjs/version-fallback.generated.d.ts

 export declare const VERSION_FALLBACK: {
-    readonly agent: "0.9.6";
+    readonly agent: "0.10.0";
     readonly tools: "0.29.0";
 };

dist/cjs/version-fallback.generated.js

@@ -5,4 +5,4 @@ "use strict";
 exports.VERSION_FALLBACK = {
-    agent: "0.9.6",
+    agent: "0.10.0",
     tools: "0.29.0",
 };

dist/esm/version-fallback.generated.d.ts

 export declare const VERSION_FALLBACK: {
-    readonly agent: "0.9.6";
+    readonly agent: "0.10.0";
     readonly tools: "0.29.0";
 };

dist/esm/version-fallback.generated.js

 export const VERSION_FALLBACK = {
-    agent: "0.9.6",
+    agent: "0.10.0",
     tools: "0.29.0",
 };

package.json

 {
   "name": "@sapiom/agent-core",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "Pure, stateless core functions for scaffolding, validating, and operating Sapiom agents — shared by the CLI and MCP packages.",
@@ -40,4 +40,4 @@ "license": "MIT",
     "esbuild": "^0.28.1",
-    "@sapiom/agent": "^0.9.6",
-    "@sapiom/agent-runtime": "^0.4.3",
+    "@sapiom/agent": "^0.10.0",
+    "@sapiom/agent-runtime": "^0.5.0",
     "@sapiom/analytics-core": "^0.2.1",
@@ -44,0 +44,0 @@ "@sapiom/tools": "^0.29.0"

skills/sapiom-agent-authoring/SKILL.md

@@ -237,6 +237,17 @@ ---
 
+The **whole snapshot** has an inclusive **256 KiB (262,144-byte)** quota,
+measured as the UTF-8 byte length of compact `JSON.stringify(snapshot)`. Keys,
+JSON punctuation, all existing values, and the value being set count together.
+Exactly 262,144 bytes is valid; 262,145 bytes is rejected. Keep compact state,
+IDs, and durable-storage references in `ctx.shared`; put bulk API responses,
+documents, or research data in durable storage and carry only the ID/reference.
+The SDK contract does not by itself make `ctx.shared.set()` a synchronous size
+gate. Hosts enforce it at execution boundaries, and older hosts may temporarily
+enforce a smaller legacy limit during rollout.
+
 **A step's `run(input, ctx)` first argument is its inbound input** — the entry input at the
 entry step, or the previous step's `goto(target, payload)` value at later steps. The entry
-input reaches only the entry step's argument; to use it in later steps, write it into
-`ctx.shared` from the entry step.
+input reaches only the entry step's argument; if it is compact and later steps need it,
+write it into `ctx.shared` from the entry step. Persist bulk input separately and carry a
+reference instead.
 
@@ -243,0 +254,0 @@ ## `ctx` Reference

templates/coding-p.../skills/sapiom-agent-authoring/SKILL.md

@@ -237,6 +237,17 @@ ---
 
+The **whole snapshot** has an inclusive **256 KiB (262,144-byte)** quota,
+measured as the UTF-8 byte length of compact `JSON.stringify(snapshot)`. Keys,
+JSON punctuation, all existing values, and the value being set count together.
+Exactly 262,144 bytes is valid; 262,145 bytes is rejected. Keep compact state,
+IDs, and durable-storage references in `ctx.shared`; put bulk API responses,
+documents, or research data in durable storage and carry only the ID/reference.
+The SDK contract does not by itself make `ctx.shared.set()` a synchronous size
+gate. Hosts enforce it at execution boundaries, and older hosts may temporarily
+enforce a smaller legacy limit during rollout.
+
 **A step's `run(input, ctx)` first argument is its inbound input** — the entry input at the
 entry step, or the previous step's `goto(target, payload)` value at later steps. The entry
-input reaches only the entry step's argument; to use it in later steps, write it into
-`ctx.shared` from the entry step.
+input reaches only the entry step's argument; if it is compact and later steps need it,
+write it into `ctx.shared` from the entry step. Persist bulk input separately and carry a
+reference instead.
 
@@ -243,0 +254,0 @@ ## `ctx` Reference

templates/coding-pause/AGENTS.md

@@ -75,3 +75,3 @@ # Working in this agent project
 - **The resumed step's `input` IS the run's result signal payload.** Annotate it with `CodingResultPayload` (from `@sapiom/tools`) — you don't have to hand-roll the shape.
-- That payload crossed a wire boundary, so it carries **no live handles** — to act on the run's sandbox, re-attach one from **`executionEnvironment`** with `ctx.sapiom.sandboxes.attach(result.executionEnvironment.id)` (`executionEnvironment` is `null` when the run provisioned none, e.g. a launch failure). Anything else the resumed step needs, stash in `ctx.shared` before pausing.
+- That payload crossed a wire boundary, so it carries **no live handles** — to act on the run's sandbox, re-attach one from **`executionEnvironment`** with `ctx.sapiom.sandboxes.attach(result.executionEnvironment.id)` (`executionEnvironment` is `null` when the run provisioned none, e.g. a launch failure). Before pausing, stash only compact state, IDs, or durable-storage references in `ctx.shared`; its whole compact-JSON snapshot has an inclusive 256 KiB UTF-8 quota. The SDK contract does not make `ctx.shared.set()` a synchronous size gate by itself; hosts enforce it at execution boundaries, and older hosts may temporarily enforce a smaller legacy limit during rollout.
 - **To stub the resume payload** (e.g. to exercise the failure branch), override `models.coding.run` _in the launching step_ — that one value is both the `run()` result and the payload the paused step resumes with. `models.coding.launch` is accepted there too.
@@ -83,2 +83,2 @@ - `gitRepository` accepts a Sapiom repository returned by `repositories.create`, `get`, or `list`; `repositories.attach` only rehydrates such a handle.
 
-A step body runs **once** on the happy path; it re-runs only on retry (after a throw). Don't rely on a value being recomputed identically across a pause/resume — capture non-deterministic values (timestamps, ids) once and pass them forward via the `goto(...)` input or `ctx.shared`.
+A step body runs **once** on the happy path; it re-runs only on retry (after a throw). Don't rely on a value being recomputed identically across a pause/resume — capture compact non-deterministic values (timestamps, ids) once and pass them forward via the `goto(...)` input or `ctx.shared`; persist bulk state and carry a reference.

templates/default/.../skills/sapiom-agent-authoring/SKILL.md

@@ -237,6 +237,17 @@ ---
 
+The **whole snapshot** has an inclusive **256 KiB (262,144-byte)** quota,
+measured as the UTF-8 byte length of compact `JSON.stringify(snapshot)`. Keys,
+JSON punctuation, all existing values, and the value being set count together.
+Exactly 262,144 bytes is valid; 262,145 bytes is rejected. Keep compact state,
+IDs, and durable-storage references in `ctx.shared`; put bulk API responses,
+documents, or research data in durable storage and carry only the ID/reference.
+The SDK contract does not by itself make `ctx.shared.set()` a synchronous size
+gate. Hosts enforce it at execution boundaries, and older hosts may temporarily
+enforce a smaller legacy limit during rollout.
+
 **A step's `run(input, ctx)` first argument is its inbound input** — the entry input at the
 entry step, or the previous step's `goto(target, payload)` value at later steps. The entry
-input reaches only the entry step's argument; to use it in later steps, write it into
-`ctx.shared` from the entry step.
+input reaches only the entry step's argument; if it is compact and later steps need it,
+write it into `ctx.shared` from the entry step. Persist bulk input separately and carry a
+reference instead.
 
@@ -243,0 +254,0 @@ ## `ctx` Reference

templates/default/AGENTS.md

@@ -75,3 +75,3 @@ # Working in this agent project
 - **The resumed step's `input` IS the run's result signal payload.** Annotate it with `CodingResultPayload` (from `@sapiom/tools`) — you don't have to hand-roll the shape.
-- That payload crossed a wire boundary, so it carries **no live handles** — to act on the run's sandbox, re-attach one from **`executionEnvironment`** with `ctx.sapiom.sandboxes.attach(result.executionEnvironment.id)` (`executionEnvironment` is `null` when the run provisioned none, e.g. a launch failure). Anything else the resumed step needs, stash in `ctx.shared` before pausing.
+- That payload crossed a wire boundary, so it carries **no live handles** — to act on the run's sandbox, re-attach one from **`executionEnvironment`** with `ctx.sapiom.sandboxes.attach(result.executionEnvironment.id)` (`executionEnvironment` is `null` when the run provisioned none, e.g. a launch failure). Before pausing, stash only compact state, IDs, or durable-storage references in `ctx.shared`; its whole compact-JSON snapshot has an inclusive 256 KiB UTF-8 quota. The SDK contract does not make `ctx.shared.set()` a synchronous size gate by itself; hosts enforce it at execution boundaries, and older hosts may temporarily enforce a smaller legacy limit during rollout.
 - **To stub the resume payload** (e.g. to exercise the failure branch), override `models.coding.run` _in the launching step_ — that one value is both the `run()` result and the payload the paused step resumes with. `models.coding.launch` is accepted there too.
@@ -83,2 +83,2 @@ - `gitRepository` accepts a Sapiom repository returned by `repositories.create`, `get`, or `list`; `repositories.attach` only rehydrates such a handle.
 
-A step body runs **once** on the happy path; it re-runs only on retry (after a throw). Don't rely on a value being recomputed identically across a pause/resume — capture non-deterministic values (timestamps, ids) once and pass them forward via the `goto(...)` input or `ctx.shared`.
+A step body runs **once** on the happy path; it re-runs only on retry (after a throw). Don't rely on a value being recomputed identically across a pause/resume — capture compact non-deterministic values (timestamps, ids) once and pass them forward via the `goto(...)` input or `ctx.shared`; persist bulk state and carry a reference.

New alerts

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

528210

0.89%

Dependency changes

• + Added

  @sapiom/agent@0.10.2
  (transitive)

• + Added

  @sapiom/agent-runtime@0.5.0
  (transitive)

• + Added

  @sapiom/tools@0.31.0
  (transitive)

• - Removed

  @sapiom/agent@0.9.6
  (transitive)

• - Removed

  @sapiom/agent-runtime@0.4.3
  (transitive)

• Updated

  @sapiom/agent@^0.10.0

• Updated

  @sapiom/agent-runtime@^0.5.0