@sequenceholdings/agent-spec 0.1.3 → 0.1.5

package/README.md

@@ -25,11 +25,16 @@ import { defineAgent } from '@sequenceholdings/agent-spec'
 export const agent = defineAgent({
   id: '680000000000000000000001',
   name: 'Support Agent',
-  model: { provider: 'anthropic', name: 'claude-sonnet-4-6' },
+  model: { provider: 'anthropic', name: 'claude-sonnet-5-5' },
   systemPrompt: 'Help the support team investigate and resolve requests.',
 })
 ```
 
+`RECOMMENDED_AGENT_MODEL` is the model new agents start on; `seq-studio agents
+init` writes it into the scaffold. A definition that omits `model` keeps the
+schema's original default, so upgrading this package never moves an existing
+agent to another model.
+
 Definitions must be pure data literals: do not read environment variables, call
 functions, or compute fields in `agent.ts`. Keep deployment targeting separate
 from a definition, then use `seq-studio agents validate`, `plan`, and `apply`.
@@ -68,6 +73,45 @@ with no such identity, such as a Lattice step without
 `run_as.service_account`, gets no function tools and records each function as
 unavailable (`no_user_identity`).
 
+## Author client proposals (preview)
+
+The upcoming `0.1.4` release adds optional `clientProposals` to text agent
+definitions. Each literal descriptor supplies its exact tool name, description
+and a bounded JSON input schema:
+
+```ts
+clientProposals: [{
+  name: 'propose_label',
+  description: 'Propose a support label for the user to review.',
+  inputSchema: {
+    type: 'object',
+    properties: { label: { type: 'string', enum: ['ready', 'needs-review'] } },
+    required: ['label'],
+    additionalProperties: false,
+  },
+}],
+```
+
+`clientProposalSchema`, `clientProposalsSchema` and the `ClientProposal` type
+are root exports. Definitions accept at most 64 uniquely named proposals,
+32,000 characters per description, 128 KiB per input schema and 512 KiB for all
+descriptors. Schemas are limited to depth 32 and 10,000 nodes. They use a finite
+JSON Schema subset: executable values and unsupported keywords such as
+`pattern`, `format`, `default` and `$ref` are rejected. Schema URL annotations
+are never fetched. Keep descriptors as authored literals so their exact
+instructions and schemas enter the captured execution definition. Omitting
+the field preserves existing definition hashes.
+
+The matching Vercel-framework runtime validates arguments, bounded to 256 KiB,
+depth 64, 50,000 nodes and 100,000 validation work units, then returns
+`{ status: 'pending_client_review', applied: false }`. This acknowledgement
+proves neither a backend apply nor client delivery. It does not execute a
+provider call or authorize a mutation.
+The application owns proposal rendering, validation, human review and any
+separate authorized write. Proposal names that collide with another resolved
+tool are rejected. Confirm package publication and matching runtime support
+before relying on this preview contract.
+
 ## Exports
 
 - `@sequenceholdings/agent-spec` provides `defineAgent`,
@@ -78,6 +122,26 @@ unavailable (`no_user_identity`).
 - `@sequenceholdings/agent-spec/yaml` provides `parseYamlAgent` only for
   migrating legacy YAML definitions.
 
+## Job request fingerprints (preview)
+
+The upcoming `0.1.4` release adds `hashJobCreateRequest` at the package root.
+Confirm registry publication before installing that version. This pure helper
+hashes the job kind, resource ID, expected source identity and exact parsed
+payload using the platform's versioned request format. It sorts object keys
+while preserving array order and string bytes. `normalizeJobRequestJson`
+normalizes dates to ISO strings and omits undefined object fields; non-JSON,
+cyclic, excessively nested or oversized input is refused with
+`JobRequestHashError` (`status` 400 or 413). The serialized input is bounded
+to 16 MiB.
+
+The fingerprint excludes transport credentials and caller identity. It is not
+an authorization grant, an admission receipt, proof that a job ran, or an
+application's business-source association. An application comparing an
+authorized admission receipt must still verify the actual caller, current
+protected intent, expected source identity and recorded job separately. Use
+the exact parsed request payload, not a display projection or reconstructed
+subset.
+
 ## Voice definitions (preview)
 
 Choose either `text` or `voice` when creating an Agent. Definitions without `mode` retain their existing text defaults, source format, and bundle hashes. `validateAgentModeUpdate` rejects changing an existing Agent's mode in either direction. Voice uses the same identity, prompt, model, native Skill references, permissions, source compiler, and bundle hashing as text; its supported authoring fields are deliberately smaller.

package/dist/agent-definition.d.ts

@@ -2,6 +2,10 @@ import { z } from 'zod';
 export { canonicalJson } from './canonical-json.js';
 export { voiceDeclarationSchema } from './voice-authoring.js';
 export type { VoiceDeclaration, VoiceDeclarationInput } from './voice-authoring.js';
+export declare const RECOMMENDED_AGENT_MODEL: {
+    readonly provider: "anthropic";
+    readonly name: "claude-sonnet-5-5";
+};
 export type UnsupportedConstraint = {
     path: string;
     type: string;
@@ -59,6 +63,11 @@ export declare const textAgentDefinitionSchema: z.ZodObject<{
     temperature: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     systemPrompt: z.ZodOptional<z.ZodString>;
     tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    clientProposals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        inputSchema: z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>>;
     mcpServers: z.ZodDefault<z.ZodArray<z.ZodString>>;
     requiredMcpServers: z.ZodDefault<z.ZodArray<z.ZodString>>;
     requiredReferences: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -338,6 +347,11 @@ export declare const agentDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObject
     temperature: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     systemPrompt: z.ZodOptional<z.ZodString>;
     tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    clientProposals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        inputSchema: z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>>;
     mcpServers: z.ZodDefault<z.ZodArray<z.ZodString>>;
     requiredMcpServers: z.ZodDefault<z.ZodArray<z.ZodString>>;
     requiredReferences: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/agent-definition.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { inputSchemaSchema } from './input-schema.js';
 import { canonicalJson, sortJson } from './canonical-json.js';
 import { voiceDeclarationSchema } from './voice-authoring.js';
+import { clientProposalsSchema } from './client-proposals.js';
 export { canonicalJson } from './canonical-json.js';
 export { voiceDeclarationSchema } from './voice-authoring.js';
 const OBJECT_ID_PATTERN = /^[0-9a-f]{24}$/;
@@ -11,6 +12,10 @@ const DEFAULT_MODEL = {
     provider: 'anthropic',
     name: 'claude-sonnet-4-5-20250929',
 };
+export const RECOMMENDED_AGENT_MODEL = {
+    provider: 'anthropic',
+    name: 'claude-sonnet-5-5',
+};
 const jsonObjectSchema = z.record(z.string(), z.unknown());
 const unsupportedConstraints = {
     integer: ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum'],
@@ -118,6 +123,7 @@ const textDefinitionBaseSchema = z
     temperature: z.number().min(0).max(1).nullish(),
     systemPrompt: z.string().optional(),
     tools: z.array(z.string()).default([]),
+    clientProposals: clientProposalsSchema.optional(),
     mcpServers: z.array(z.string()).default([]),
     requiredMcpServers: z.array(z.string()).default([]),
     requiredReferences: z.array(agentReferenceSchema).optional(),
@@ -146,6 +152,14 @@ export const textAgentDefinitionSchema = textDefinitionBaseSchema.safeExtend({
     mode: z.literal('text').optional(),
     voice: z.never().optional(),
 }).superRefine((definition, context) => {
+    if (definition.framework === 'claude-agent' && (definition.clientProposals?.length ?? 0) > 0) {
+        context.addIssue({ code: 'custom', path: ['clientProposals'], message: 'Client proposals require the Vercel tool runtime' });
+    }
+    for (const [index, proposal] of (definition.clientProposals ?? []).entries()) {
+        if (definition.tools.includes(proposal.name)) {
+            context.addIssue({ code: 'custom', path: ['clientProposals', index, 'name'], message: 'Client proposal name collides with a selected built-in tool' });
+        }
+    }
     for (const [index, serverId] of definition.requiredMcpServers.entries()) {
         if (definition.mcpServers.includes(serverId))
             continue;

package/dist/client-proposals.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const CLIENT_PROPOSAL_LIMITS: {
+    readonly count: 64;
+    readonly descriptionLength: 32000;
+    readonly schemaBytes: number;
+    readonly totalBytes: number;
+    readonly schemaDepth: 32;
+    readonly schemaNodes: 10000;
+};
+export declare const clientProposalSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    inputSchema: z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type ClientProposal = z.infer<typeof clientProposalSchema>;
+export declare const clientProposalsSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    inputSchema: z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>>;

package/dist/client-proposals.js

@@ -0,0 +1,172 @@
+import { z } from 'zod';
+export const CLIENT_PROPOSAL_LIMITS = {
+    count: 64, descriptionLength: 32_000, schemaBytes: 128 * 1024,
+    totalBytes: 512 * 1024, schemaDepth: 32, schemaNodes: 10_000,
+};
+const TYPES = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']);
+const RESERVED_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
+const ANNOTATIONS = new Set(['$schema', 'title', 'description']);
+const NUMBER_KEYS = new Set(['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum']);
+const SIZE_KEYS = new Set(['minLength', 'maxLength', 'minItems', 'maxItems']);
+const CHILD_KEYS = new Set(['items', 'additionalProperties', 'propertyNames']);
+const UNION_KEYS = new Set(['anyOf', 'oneOf', 'allOf']);
+const KEYWORDS = new Set([...ANNOTATIONS, ...NUMBER_KEYS, ...SIZE_KEYS, ...CHILD_KEYS, ...UNION_KEYS,
+    'type', 'properties', 'required', 'enum', 'const']);
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireBoundedJson(value) {
+    const seen = new Set();
+    const pending = [{ value, depth: 0 }];
+    let nodes = 0;
+    while (pending.length > 0) {
+        const item = pending.pop();
+        if (!item)
+            break;
+        if (++nodes > CLIENT_PROPOSAL_LIMITS.schemaNodes || item.depth > CLIENT_PROPOSAL_LIMITS.schemaDepth) {
+            throw new Error('Client proposal schema exceeds its depth or node limit');
+        }
+        const current = item.value;
+        if (typeof current === 'string' && Buffer.byteLength(current) > CLIENT_PROPOSAL_LIMITS.schemaBytes) {
+            throw new Error('Client proposal schema exceeds its byte limit');
+        }
+        if (current === null || typeof current === 'string' || typeof current === 'boolean')
+            continue;
+        if (typeof current === 'number' && Number.isFinite(current))
+            continue;
+        if (typeof current !== 'object' || current === null)
+            throw new Error('Client proposal schema must be literal JSON');
+        requireLiteralContainer({ current, seen, pending, depth: item.depth });
+    }
+    if (Buffer.byteLength(JSON.stringify(value)) > CLIENT_PROPOSAL_LIMITS.schemaBytes) {
+        throw new Error('Client proposal schema exceeds its byte limit');
+    }
+}
+function requireLiteralContainer({ current, seen, pending, depth }) {
+    const prototype = Object.getPrototypeOf(current);
+    if ((!Array.isArray(current) && prototype !== Object.prototype && prototype !== null) || seen.has(current)) {
+        throw new Error('Client proposal schema must be acyclic literal JSON');
+    }
+    seen.add(current);
+    const keys = Reflect.ownKeys(current);
+    if (Array.isArray(current))
+        requireLiteralArray({ value: current, keys });
+    for (const key of keys) {
+        if (Array.isArray(current) && key === 'length')
+            continue;
+        if (typeof key !== 'string' || RESERVED_NAMES.has(key))
+            throw new Error('Client proposal schema contains an unsupported key');
+        const descriptor = Object.getOwnPropertyDescriptor(current, key);
+        if (!descriptor || !('value' in descriptor) || !descriptor.enumerable)
+            throw new Error('Client proposal schema must contain JSON values');
+        pending.push({ value: descriptor.value, depth: depth + 1 });
+    }
+}
+function requireLiteralArray({ value, keys }) {
+    if (Object.getPrototypeOf(value) !== Array.prototype || keys.length !== value.length + 1) {
+        throw new Error('Client proposal schema arrays must be dense literal JSON');
+    }
+    for (let index = 0; index < value.length; index++) {
+        if (!Object.hasOwn(value, String(index)))
+            throw new Error('Client proposal schema arrays must be dense literal JSON');
+    }
+}
+function requireType(value) {
+    const types = Array.isArray(value) ? value : [value];
+    if (types.length === 0 || types.length > TYPES.size || types.some(type => typeof type !== 'string' || !TYPES.has(type))
+        || new Set(types).size !== types.length)
+        throw new Error('Client proposal schema has an invalid type');
+}
+function requireProperties(value) {
+    if (!isObject(value) || Object.keys(value).length > 512)
+        throw new Error('Client proposal properties must be a bounded object');
+    for (const child of Object.values(value))
+        requireSchema(child);
+}
+function requireRequired({ value, properties }) {
+    if (!Array.isArray(value) || value.some(name => typeof name !== 'string') || new Set(value).size !== value.length) {
+        throw new Error('Client proposal required must contain unique property names');
+    }
+    if (value.some(name => !isObject(properties) || !Object.hasOwn(properties, name))) {
+        throw new Error('Client proposal required must name declared properties');
+    }
+}
+function requireBound({ key, value }) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        throw new Error(`Client proposal ${key} must be a finite number`);
+    if (SIZE_KEYS.has(key) && (!Number.isSafeInteger(value) || value < 0)) {
+        throw new Error(`Client proposal ${key} must be a nonnegative integer`);
+    }
+}
+function requireEntry({ key, entry, schema }) {
+    if (!KEYWORDS.has(key))
+        throw new Error(`Unsupported client proposal schema keyword: ${key}`);
+    if (ANNOTATIONS.has(key)) {
+        if (typeof entry !== 'string')
+            throw new Error(`Client proposal ${key} must be a string`);
+    }
+    else if (NUMBER_KEYS.has(key) || SIZE_KEYS.has(key))
+        requireBound({ key, value: entry });
+    else if (key === 'type')
+        requireType(entry);
+    else if (CHILD_KEYS.has(key))
+        requireSchema(entry);
+    else if (UNION_KEYS.has(key)) {
+        if (!Array.isArray(entry) || entry.length === 0 || entry.length > 32)
+            throw new Error(`Client proposal ${key} requires 1–32 schemas`);
+        for (const child of entry)
+            requireSchema(child);
+    }
+    else if (key === 'properties')
+        requireProperties(entry);
+    else if (key === 'required')
+        requireRequired({ value: entry, properties: schema.properties });
+    else if (key === 'enum') {
+        if (!Array.isArray(entry) || entry.length === 0 || entry.length > 512)
+            throw new Error('Client proposal enum must be a bounded nonempty array');
+    }
+}
+function requireSchema(value) {
+    if (typeof value === 'boolean')
+        return;
+    if (!isObject(value))
+        throw new Error('Client proposal schema nodes must be objects or booleans');
+    for (const [key, entry] of Object.entries(value))
+        requireEntry({ key, entry, schema: value });
+}
+const literalJsonSchema = z.unknown().superRefine((value, context) => {
+    try {
+        requireBoundedJson(value);
+    }
+    catch (error) {
+        context.addIssue({ code: 'custom', message: error instanceof Error ? error.message : 'Invalid client proposal JSON' });
+    }
+});
+const proposalInputSchema = literalJsonSchema.pipe(z.record(z.string(), z.unknown())).superRefine((value, context) => {
+    try {
+        if (value.type !== 'object')
+            throw new Error('Client proposal root schema type must be object');
+        requireSchema(value);
+    }
+    catch (error) {
+        context.addIssue({ code: 'custom', message: error instanceof Error ? error.message : 'Invalid client proposal schema' });
+    }
+});
+export const clientProposalSchema = z.strictObject({
+    name: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,63}$/).refine(name => !RESERVED_NAMES.has(name), 'Reserved client proposal name'),
+    description: z.string().min(1).max(CLIENT_PROPOSAL_LIMITS.descriptionLength),
+    inputSchema: proposalInputSchema,
+});
+export const clientProposalsSchema = z.array(clientProposalSchema).max(CLIENT_PROPOSAL_LIMITS.count).superRefine((value, context) => {
+    if (new Set(value.map(proposal => proposal.name)).size !== value.length) {
+        context.addIssue({ code: 'custom', message: 'Client proposal names must be unique' });
+    }
+    try {
+        if (Buffer.byteLength(JSON.stringify(value)) > CLIENT_PROPOSAL_LIMITS.totalBytes) {
+            context.addIssue({ code: 'custom', message: 'Client proposal descriptors exceed their total byte limit' });
+        }
+    }
+    catch {
+        context.addIssue({ code: 'custom', message: 'Client proposal descriptors must be literal JSON' });
+    }
+});

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export * from './agent-definition.js';
 export * from './voice.js';
+export * from './job-request-hash.js';
+export * from './client-proposals.js';

package/dist/index.js

@@ -1,2 +1,4 @@
 export * from './agent-definition.js';
 export * from './voice.js';
+export * from './job-request-hash.js';
+export * from './client-proposals.js';

package/dist/job-request-hash.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+export declare const JobCreateKindSchema: z.ZodEnum<{
+    agent: "agent";
+    workflow: "workflow";
+}>;
+export type JobCreateKind = z.infer<typeof JobCreateKindSchema>;
+export type JobRequestJsonValue = null | boolean | number | string | JobRequestJsonValue[] | {
+    [key: string]: JobRequestJsonValue;
+};
+export declare const JobRequestExecutionIdentitySchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodString;
+    definitionSha256: z.ZodString;
+}, z.core.$strict>;
+export type JobRequestExecutionIdentity = z.infer<typeof JobRequestExecutionIdentitySchema>;
+export interface JobCreateRequestFingerprintInput {
+    kind: JobCreateKind;
+    resourceId: string;
+    expectedIdentity: JobRequestExecutionIdentity;
+    payload: unknown;
+}
+export declare class JobRequestHashError extends Error {
+    readonly status: 400 | 413;
+    constructor(status: 400 | 413, message: string);
+}
+export declare function normalizeJobRequestJson(value: unknown): JobRequestJsonValue;
+export declare function hashJobCreateRequest({ kind, resourceId, expectedIdentity, payload }: JobCreateRequestFingerprintInput): string;

package/dist/job-request-hash.js

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { canonicalJson } from './canonical-json.js';
+const MAX_JSON_BYTES = 16 * 1024 * 1024;
+export const JobCreateKindSchema = z.enum(['agent', 'workflow']);
+export const JobRequestExecutionIdentitySchema = z.strictObject({
+    id: z.string().min(1).max(128).regex(/^[A-Za-z0-9_-]+$/),
+    version: z.string().min(1).max(128),
+    definitionSha256: z.string().regex(/^[a-f0-9]{64}$/),
+});
+export class JobRequestHashError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'JobRequestHashError';
+    }
+}
+function assertJsonValue({ value, ancestors, depth }) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean'
+        || typeof value === 'number' && Number.isFinite(value))
+        return;
+    if (typeof value !== 'object' || !value || depth > 64 || ancestors.has(value)) {
+        throw new JobRequestHashError(400, 'Job admission requires bounded JSON values.');
+    }
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime()))
+            throw new JobRequestHashError(400, 'Job admission contains an invalid date.');
+        return;
+    }
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+        throw new JobRequestHashError(400, 'Job admission requires plain JSON objects.');
+    }
+    ancestors.add(value);
+    const values = Array.isArray(value) ? value : Object.values(value).filter((entry) => entry !== undefined);
+    for (const entry of values)
+        assertJsonValue({ value: entry, ancestors, depth: depth + 1 });
+    ancestors.delete(value);
+}
+export function normalizeJobRequestJson(value) {
+    assertJsonValue({ value, ancestors: new Set(), depth: 0 });
+    const encoded = JSON.stringify(value);
+    if (Buffer.byteLength(encoded) > MAX_JSON_BYTES)
+        throw new JobRequestHashError(413, 'Job admission exceeds the 16 MiB JSON budget.');
+    return JSON.parse(encoded);
+}
+export function hashJobCreateRequest({ kind, resourceId, expectedIdentity, payload }) {
+    const parsed = z.strictObject({ kind: JobCreateKindSchema, resourceId: z.string().min(1).max(128),
+        expectedIdentity: JobRequestExecutionIdentitySchema }).safeParse({ kind, resourceId, expectedIdentity });
+    if (!parsed.success)
+        throw new JobRequestHashError(400, 'Job request fingerprint requires a valid expected execution identity.');
+    const envelope = normalizeJobRequestJson({ format: 'agents-job-create-request-v1', ...parsed.data, payload });
+    return createHash('sha256').update(canonicalJson(envelope)).digest('hex');
+}

package/dist/voice-authority-contracts.d.ts

@@ -188,8 +188,8 @@ export declare const voiceVerificationAttemptSchema: z.ZodObject<{
     attemptedAt: z.ZodISODateTime;
     attemptNumber: z.ZodNumber;
     status: z.ZodEnum<{
-        verified: "verified";
         pending: "pending";
+        verified: "verified";
         rejected: "rejected";
         uncertain: "uncertain";
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sequenceholdings/agent-spec",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Typed agent definition contract, compiler, hashing, and migration utilities",
   "license": "UNLICENSED",
   "repository": {