New:Socket for Asana Is Now Available.Learn more
Get Started

@sapiom/agent

Package Overview
Dependencies
Maintainers
4
Versions
27
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@sapiom/agent - npm Package Compare versions

Comparing version
0.12.2
to
0.13.0
+37
dist/cjs/package-inventory.d.ts
import { z } from "zod/v4";
export declare const PACKAGE_INVENTORY_PROTOCOL: 1;
export type PackageInventoryVersion = {
readonly kind: "working-tree";
readonly workspaceKey: string;
readonly revision: `sha256:${string}`;
} | {
readonly kind: "bundle";
readonly bundleDigest: `sha256:${string}`;
};
export type PackageInventoryIdentityIssue = "identity-pending" | "identity-unavailable" | "identity-invalid" | "duplicate-agent-key";
interface PackageInventoryAgentBase {
readonly agentKey: string;
readonly path: string;
readonly entrypoint: string;
}
export type PackageInventoryAgent = PackageInventoryAgentBase & ({
readonly identityStatus: "canonical";
readonly identityIssue?: never;
readonly candidateAgentKey?: never;
} | {
readonly identityStatus: "provisional";
readonly identityIssue: Exclude<PackageInventoryIdentityIssue, "duplicate-agent-key">;
readonly candidateAgentKey?: never;
} | {
readonly identityStatus: "provisional";
readonly identityIssue: "duplicate-agent-key";
readonly candidateAgentKey: string;
});
export interface PackageInventory {
readonly protocol: typeof PACKAGE_INVENTORY_PROTOCOL;
readonly version: PackageInventoryVersion;
readonly status: "complete" | "degraded";
readonly agents: readonly PackageInventoryAgent[];
}
export declare const packageInventorySchema: z.ZodType<PackageInventory>;
export {};
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.packageInventorySchema = exports.PACKAGE_INVENTORY_PROTOCOL = void 0;
const v4_1 = require("zod/v4");
exports.PACKAGE_INVENTORY_PROTOCOL = 1;
const SHA256 = /^sha256:[0-9a-f]{64}$/;
function hasControlCharacter(value) {
return [...value].some((character) => {
const code = character.codePointAt(0);
return code <= 0x1f || (code >= 0x7f && code <= 0x9f);
});
}
function canonicalAgentKey(value) {
return (value !== "" &&
value === value.trim() &&
value !== "." &&
value !== ".." &&
!value.startsWith("local:") &&
!hasControlCharacter(value) &&
!value.includes("/") &&
!value.includes("\\"));
}
function provisionalAgentKey(value) {
if (canonicalAgentKey(value))
return true;
if (!value.startsWith("local:") ||
value !== value.trim() ||
hasControlCharacter(value)) {
return false;
}
const relative = value.slice("local:".length);
return (relative !== "" &&
!/^[A-Za-z]:(?:$|\/)/.test(relative) &&
!relative.includes("\\") &&
relative
.split("/")
.every((segment) => segment !== "" && segment !== "." && segment !== ".."));
}
function relativePosixPath(value, allowRoot) {
if (allowRoot && value === ".")
return true;
if (value === "" ||
value !== value.trim() ||
value.startsWith("/") ||
/^[A-Za-z]:\//.test(value) ||
value.includes("\\") ||
hasControlCharacter(value)) {
return false;
}
return value
.split("/")
.every((segment) => segment !== "" && segment !== "." && segment !== "..");
}
const digestSchema = v4_1.z
.string()
.regex(SHA256, "Expected lowercase sha256:<64 hex characters>")
.transform((value) => value);
const canonicalAgentKeySchema = v4_1.z
.string()
.refine(canonicalAgentKey, "Expected a safe canonical agent key");
const provisionalAgentKeySchema = v4_1.z
.string()
.refine(provisionalAgentKey, "Expected a safe package inventory agent key");
const packagePathSchema = v4_1.z
.string()
.refine((value) => relativePosixPath(value, true), "Expected a package-root-relative POSIX path");
const entrypointSchema = v4_1.z
.string()
.refine((value) => relativePosixPath(value, false), "Expected an agent-root-relative POSIX path");
const packageInventoryAgentSchema = v4_1.z
.object({
agentKey: provisionalAgentKeySchema,
identityStatus: v4_1.z.enum(["canonical", "provisional"]),
identityIssue: v4_1.z
.enum([
"identity-pending",
"identity-unavailable",
"identity-invalid",
"duplicate-agent-key",
])
.optional(),
candidateAgentKey: canonicalAgentKeySchema.optional(),
path: packagePathSchema,
entrypoint: entrypointSchema,
})
.strict()
.superRefine((agent, context) => {
if (agent.identityStatus === "canonical") {
if (!canonicalAgentKey(agent.agentKey)) {
context.addIssue({
code: "custom",
path: ["agentKey"],
message: "A canonical inventory agent requires a canonical agent key",
});
}
if (agent.identityIssue !== undefined ||
agent.candidateAgentKey !== undefined) {
context.addIssue({
code: "custom",
message: "A canonical inventory agent cannot carry provisional identity metadata",
});
}
return;
}
if (agent.identityIssue === undefined) {
context.addIssue({
code: "custom",
path: ["identityIssue"],
message: "A provisional inventory agent requires an identity issue",
});
}
if (agent.identityIssue === "duplicate-agent-key" &&
agent.candidateAgentKey === undefined) {
context.addIssue({
code: "custom",
path: ["candidateAgentKey"],
message: "A duplicate identity requires its ambiguous candidate key",
});
}
if (agent.identityIssue !== "duplicate-agent-key" &&
agent.candidateAgentKey !== undefined) {
context.addIssue({
code: "custom",
path: ["candidateAgentKey"],
message: "Only a duplicate identity can carry a candidate key",
});
}
});
const packageInventoryVersionSchema = v4_1.z.discriminatedUnion("kind", [
v4_1.z
.object({
kind: v4_1.z.literal("working-tree"),
workspaceKey: v4_1.z.string().trim().min(1),
revision: digestSchema,
})
.strict(),
v4_1.z
.object({
kind: v4_1.z.literal("bundle"),
bundleDigest: digestSchema,
})
.strict(),
]);
function compareText(left, right) {
return left === right ? 0 : left < right ? -1 : 1;
}
exports.packageInventorySchema = v4_1.z
.object({
protocol: v4_1.z.literal(exports.PACKAGE_INVENTORY_PROTOCOL),
version: packageInventoryVersionSchema,
status: v4_1.z.enum(["complete", "degraded"]),
agents: v4_1.z.array(packageInventoryAgentSchema),
})
.strict()
.superRefine((inventory, context) => {
const agentKeys = new Set();
const entrypoints = new Set();
for (const [index, agent] of inventory.agents.entries()) {
if (agentKeys.has(agent.agentKey)) {
context.addIssue({
code: "custom",
path: ["agents", index, "agentKey"],
message: `Duplicate agentKey: ${agent.agentKey}`,
});
}
agentKeys.add(agent.agentKey);
const entrypointKey = `${agent.path}\u0000${agent.entrypoint}`;
if (entrypoints.has(entrypointKey)) {
context.addIssue({
code: "custom",
path: ["agents", index, "entrypoint"],
message: "Duplicate agent path and entrypoint",
});
}
entrypoints.add(entrypointKey);
}
const hasProvisional = inventory.agents.some((agent) => agent.identityStatus === "provisional");
if (hasProvisional && inventory.status !== "degraded") {
context.addIssue({
code: "custom",
path: ["status"],
message: "An inventory with provisional identities must be degraded",
});
}
if (inventory.version.kind === "bundle" &&
(hasProvisional || inventory.status !== "complete")) {
context.addIssue({
code: "custom",
path: ["agents"],
message: "A bundle inventory must be complete and contain only canonical identities",
});
}
})
.transform((inventory) => ({
...inventory,
agents: [...inventory.agents].sort((left, right) => compareText(left.agentKey, right.agentKey) ||
compareText(left.path, right.path) ||
compareText(left.entrypoint, right.entrypoint)),
}));
import { z } from "zod/v4";
export declare const PACKAGE_INVENTORY_PROTOCOL: 1;
export type PackageInventoryVersion = {
readonly kind: "working-tree";
readonly workspaceKey: string;
readonly revision: `sha256:${string}`;
} | {
readonly kind: "bundle";
readonly bundleDigest: `sha256:${string}`;
};
export type PackageInventoryIdentityIssue = "identity-pending" | "identity-unavailable" | "identity-invalid" | "duplicate-agent-key";
interface PackageInventoryAgentBase {
readonly agentKey: string;
readonly path: string;
readonly entrypoint: string;
}
export type PackageInventoryAgent = PackageInventoryAgentBase & ({
readonly identityStatus: "canonical";
readonly identityIssue?: never;
readonly candidateAgentKey?: never;
} | {
readonly identityStatus: "provisional";
readonly identityIssue: Exclude<PackageInventoryIdentityIssue, "duplicate-agent-key">;
readonly candidateAgentKey?: never;
} | {
readonly identityStatus: "provisional";
readonly identityIssue: "duplicate-agent-key";
readonly candidateAgentKey: string;
});
export interface PackageInventory {
readonly protocol: typeof PACKAGE_INVENTORY_PROTOCOL;
readonly version: PackageInventoryVersion;
readonly status: "complete" | "degraded";
readonly agents: readonly PackageInventoryAgent[];
}
export declare const packageInventorySchema: z.ZodType<PackageInventory>;
export {};
import { z } from "zod/v4";
export const PACKAGE_INVENTORY_PROTOCOL = 1;
const SHA256 = /^sha256:[0-9a-f]{64}$/;
function hasControlCharacter(value) {
return [...value].some((character) => {
const code = character.codePointAt(0);
return code <= 0x1f || (code >= 0x7f && code <= 0x9f);
});
}
function canonicalAgentKey(value) {
return (value !== "" &&
value === value.trim() &&
value !== "." &&
value !== ".." &&
!value.startsWith("local:") &&
!hasControlCharacter(value) &&
!value.includes("/") &&
!value.includes("\\"));
}
function provisionalAgentKey(value) {
if (canonicalAgentKey(value))
return true;
if (!value.startsWith("local:") ||
value !== value.trim() ||
hasControlCharacter(value)) {
return false;
}
const relative = value.slice("local:".length);
return (relative !== "" &&
!/^[A-Za-z]:(?:$|\/)/.test(relative) &&
!relative.includes("\\") &&
relative
.split("/")
.every((segment) => segment !== "" && segment !== "." && segment !== ".."));
}
function relativePosixPath(value, allowRoot) {
if (allowRoot && value === ".")
return true;
if (value === "" ||
value !== value.trim() ||
value.startsWith("/") ||
/^[A-Za-z]:\//.test(value) ||
value.includes("\\") ||
hasControlCharacter(value)) {
return false;
}
return value
.split("/")
.every((segment) => segment !== "" && segment !== "." && segment !== "..");
}
const digestSchema = z
.string()
.regex(SHA256, "Expected lowercase sha256:<64 hex characters>")
.transform((value) => value);
const canonicalAgentKeySchema = z
.string()
.refine(canonicalAgentKey, "Expected a safe canonical agent key");
const provisionalAgentKeySchema = z
.string()
.refine(provisionalAgentKey, "Expected a safe package inventory agent key");
const packagePathSchema = z
.string()
.refine((value) => relativePosixPath(value, true), "Expected a package-root-relative POSIX path");
const entrypointSchema = z
.string()
.refine((value) => relativePosixPath(value, false), "Expected an agent-root-relative POSIX path");
const packageInventoryAgentSchema = z
.object({
agentKey: provisionalAgentKeySchema,
identityStatus: z.enum(["canonical", "provisional"]),
identityIssue: z
.enum([
"identity-pending",
"identity-unavailable",
"identity-invalid",
"duplicate-agent-key",
])
.optional(),
candidateAgentKey: canonicalAgentKeySchema.optional(),
path: packagePathSchema,
entrypoint: entrypointSchema,
})
.strict()
.superRefine((agent, context) => {
if (agent.identityStatus === "canonical") {
if (!canonicalAgentKey(agent.agentKey)) {
context.addIssue({
code: "custom",
path: ["agentKey"],
message: "A canonical inventory agent requires a canonical agent key",
});
}
if (agent.identityIssue !== undefined ||
agent.candidateAgentKey !== undefined) {
context.addIssue({
code: "custom",
message: "A canonical inventory agent cannot carry provisional identity metadata",
});
}
return;
}
if (agent.identityIssue === undefined) {
context.addIssue({
code: "custom",
path: ["identityIssue"],
message: "A provisional inventory agent requires an identity issue",
});
}
if (agent.identityIssue === "duplicate-agent-key" &&
agent.candidateAgentKey === undefined) {
context.addIssue({
code: "custom",
path: ["candidateAgentKey"],
message: "A duplicate identity requires its ambiguous candidate key",
});
}
if (agent.identityIssue !== "duplicate-agent-key" &&
agent.candidateAgentKey !== undefined) {
context.addIssue({
code: "custom",
path: ["candidateAgentKey"],
message: "Only a duplicate identity can carry a candidate key",
});
}
});
const packageInventoryVersionSchema = z.discriminatedUnion("kind", [
z
.object({
kind: z.literal("working-tree"),
workspaceKey: z.string().trim().min(1),
revision: digestSchema,
})
.strict(),
z
.object({
kind: z.literal("bundle"),
bundleDigest: digestSchema,
})
.strict(),
]);
function compareText(left, right) {
return left === right ? 0 : left < right ? -1 : 1;
}
export const packageInventorySchema = z
.object({
protocol: z.literal(PACKAGE_INVENTORY_PROTOCOL),
version: packageInventoryVersionSchema,
status: z.enum(["complete", "degraded"]),
agents: z.array(packageInventoryAgentSchema),
})
.strict()
.superRefine((inventory, context) => {
const agentKeys = new Set();
const entrypoints = new Set();
for (const [index, agent] of inventory.agents.entries()) {
if (agentKeys.has(agent.agentKey)) {
context.addIssue({
code: "custom",
path: ["agents", index, "agentKey"],
message: `Duplicate agentKey: ${agent.agentKey}`,
});
}
agentKeys.add(agent.agentKey);
const entrypointKey = `${agent.path}\u0000${agent.entrypoint}`;
if (entrypoints.has(entrypointKey)) {
context.addIssue({
code: "custom",
path: ["agents", index, "entrypoint"],
message: "Duplicate agent path and entrypoint",
});
}
entrypoints.add(entrypointKey);
}
const hasProvisional = inventory.agents.some((agent) => agent.identityStatus === "provisional");
if (hasProvisional && inventory.status !== "degraded") {
context.addIssue({
code: "custom",
path: ["status"],
message: "An inventory with provisional identities must be degraded",
});
}
if (inventory.version.kind === "bundle" &&
(hasProvisional || inventory.status !== "complete")) {
context.addIssue({
code: "custom",
path: ["agents"],
message: "A bundle inventory must be complete and contain only canonical identities",
});
}
})
.transform((inventory) => ({
...inventory,
agents: [...inventory.agents].sort((left, right) => compareText(left.agentKey, right.agentKey) ||
compareText(left.path, right.path) ||
compareText(left.entrypoint, right.entrypoint)),
}));
+11
-0
# @sapiom/orchestration
## 0.13.0
### Minor Changes
- 917c930: Add `PACKAGE_INVENTORY_PROTOCOL`, `packageInventorySchema`, and the public package-inventory types for validating versioned working-tree and immutable-bundle agent inventories.
### Patch Changes
- Updated dependencies [41ce013]
- @sapiom/tools@0.34.0
## 0.12.2

@@ -4,0 +15,0 @@

+2
-0

@@ -25,3 +25,5 @@ export { DIRECTIVE_KIND, isContinue, isRetry, isPause, isTerminate, isFail } from './directives.js';

export type { AgentManifest, AgentStepManifest, ManifestTransition } from './manifest.js';
export { PACKAGE_INVENTORY_PROTOCOL, packageInventorySchema } from './package-inventory.js';
export type { PackageInventory, PackageInventoryAgent, PackageInventoryIdentityIssue, PackageInventoryVersion, } from './package-inventory.js';
export { buildManifest, validateGraph, assertValidGraph } from './build-manifest.js';
export type { GraphValidation } from './build-manifest.js';
+4
-1
"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.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;
exports.assertValidGraph = exports.validateGraph = exports.buildManifest = exports.packageInventorySchema = exports.PACKAGE_INVENTORY_PROTOCOL = 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");

@@ -61,2 +61,5 @@ Object.defineProperty(exports, "DIRECTIVE_KIND", { enumerable: true, get: function () { return directives_js_1.DIRECTIVE_KIND; } });

Object.defineProperty(exports, "agentManifestSchema", { enumerable: true, get: function () { return manifest_js_1.agentManifestSchema; } });
var package_inventory_js_1 = require("./package-inventory.js");
Object.defineProperty(exports, "PACKAGE_INVENTORY_PROTOCOL", { enumerable: true, get: function () { return package_inventory_js_1.PACKAGE_INVENTORY_PROTOCOL; } });
Object.defineProperty(exports, "packageInventorySchema", { enumerable: true, get: function () { return package_inventory_js_1.packageInventorySchema; } });
var build_manifest_js_1 = require("./build-manifest.js");

@@ -63,0 +66,0 @@ Object.defineProperty(exports, "buildManifest", { enumerable: true, get: function () { return build_manifest_js_1.buildManifest; } });

@@ -25,3 +25,5 @@ export { DIRECTIVE_KIND, isContinue, isRetry, isPause, isTerminate, isFail } from './directives.js';

export type { AgentManifest, AgentStepManifest, ManifestTransition } from './manifest.js';
export { PACKAGE_INVENTORY_PROTOCOL, packageInventorySchema } from './package-inventory.js';
export type { PackageInventory, PackageInventoryAgent, PackageInventoryIdentityIssue, PackageInventoryVersion, } from './package-inventory.js';
export { buildManifest, validateGraph, assertValidGraph } from './build-manifest.js';
export type { GraphValidation } from './build-manifest.js';

@@ -13,2 +13,3 @@ export { DIRECTIVE_KIND, isContinue, isRetry, isPause, isTerminate, isFail } from './directives.js';

export { MANIFEST_PROTOCOL, agentManifestSchema } from './manifest.js';
export { PACKAGE_INVENTORY_PROTOCOL, packageInventorySchema } from './package-inventory.js';
export { buildManifest, validateGraph, assertValidGraph } from './build-manifest.js';
{
"name": "@sapiom/agent",
"version": "0.12.2",
"version": "0.13.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.",

@@ -37,3 +37,3 @@ "license": "MIT",

"dependencies": {
"@sapiom/tools": "^0.33.0"
"@sapiom/tools": "^0.34.0"
},

@@ -40,0 +40,0 @@ "peerDependencies": {

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet