@sequenceholdings/agent-spec 0.1.2 → 0.1.4

package/README.md

@@ -5,6 +5,12 @@ Preview SDK for authoring typed Sequence agent definitions.
 The package is versioned independently and its API may change before a stable
 release. Use Node.js 20 or later.
 
+Agents is a workflow-agnostic platform primitive. The schema, runtime, and
+deployment path own generic agent capabilities; deployed agent bundles own
+prompts, tools, and product behavior. Primitive code must not branch on an
+agent ID or product identity. See
+[Platform primitive boundaries](../../../docs/platform/platform-primitives.md).
+
 ## Install
 
 ```bash
@@ -28,6 +34,79 @@ 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`.
 
+## Require a declared dependency
+
+Declared MCP servers, skills, and subagents are optional by default: when the
+caller cannot use one, that run proceeds without it and records why. List a
+dependency in `requiredReferences` when the agent must refuse to run, before
+any model call, if it is unavailable:
+
+```ts
+mcpServers: ['support-data'],
+requiredReferences: [{ kind: 'mcp_server', id: 'support-data' }],
+```
+
+Each entry must also be declared in its matching `mcpServers`, `skills`,
+`subagents`, or `managedFunctions` list. Valid kinds are `mcp_server`, `skill`,
+`subagent`, and `managed_function`. `requiredMcpServers` remains supported and
+means the same as listing those servers here.
+
+## Call Managed Functions as tools
+
+List Managed Functions by slug (or id) in `managedFunctions` to give the agent
+one tool per function, named `call_function_<slug>`:
+
+```ts
+managedFunctions: ['loan-lookup'],
+requiredReferences: [{ kind: 'managed_function', id: 'loan-lookup' }],
+```
+
+Each call runs as whoever runs the agent: the person in chat, or the step's
+service account in a Lattice process. That principal needs its own `invoker`
+grant on the function; listing a function on an agent never grants it. A run
+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`,
@@ -37,3 +116,76 @@ from a definition, then use `seq-studio agents validate`, `plan`, and `apply`.
   imports or executes agent source.
 - `@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.
+
+```ts
+import { defineAgent } from '@sequenceholdings/agent-spec'
+
+export const assistant = defineAgent({
+  id: '680000000000000000000002',
+  name: 'Voice Assistant',
+  mode: 'voice',
+  model: { provider: 'supported-provider', name: 'supported-model' },
+  systemPrompt: 'Be helpful. Answer general questions using these reviewed public facts.',
+  skills: ['example-welcome-skill'],
+  voice: {
+    schemaVersion: '1',
+    voice: 'supported-voice',
+    language: 'en',
+    firstMessage: 'Hello. How can I help?',
+    procedures: [{
+      key: 'welcome',
+      name: 'Welcome',
+      instructions: '# Welcome\nAsk how you can help.\n',
+      activationDescription: 'When a conversation begins.',
+      source: { skillId: 'example-welcome-skill' },
+      toolAliases: [],
+      subprocedures: [],
+    }],
+    tools: [],
+  },
+})
+```
+
+Model and voice names in this example are placeholders for the server-supported catalog. `validateVoiceAuthoringOptions` checks that catalog; syntactic validation alone does not authorize a model, function, deployment, or call. Runtime identities, environment settings, phone numbers, credentials, provider resources, raw provider configuration, and tool-review assertions are excluded from the authored definition. Text execution settings such as MCP servers, subagents, and framework overrides are rejected on Voice Agents.
+
+Each captured procedure preserves exact Markdown, its name, activation description, native source identity, required tool aliases, and local subprocedure references. `contentHash` is recomputed from the captured name and instructions; it is not a native Skill version. Procedure keys, dependency sets, tool aliases, and field mappings have canonical ordering. Duplicate, missing, and cyclic dependencies fail validation. An empty activation description is allowed for a procedure referenced by another declared procedure. Saving a library Skill does not update captured content; an authorized explicit capture/refresh updates a draft. Consumers enforce current source permissions and optimistic revisions before persistence.
+
+Authored tools reference an existing Managed Function and operation. Optional input/output mappings support top-level field renames only; input mappings map public `argument` to function `parameter`, and output mappings map function `field` to public `result`. Empty mappings preserve the reviewed operation schema's existing public field names. Publication must validate every mapping against that operation's current input/output schemas and reserved runtime fields. Executable schemas and authority requirements come from the reviewed server catalog, not the author. `projectVoiceAuthoring` produces a deterministic local digest; it makes no promise that a future provider compilation will produce identical output.
+
+The root export also provides `VoiceAuthoringService` and `VoiceCallService` interfaces and strict contracts for drafts, publication, call admission, tool authority, verification, action receipts, operator limits, provider evidence, completed runs, and authorized audio responses. Publication validation presents both each concrete function binding and its operation policy; `hashVoiceToolReviewBinding` binds reviewer confirmation to both. These are data contracts and pure validation/transition helpers. Their consumers must implement current authorization, transactional claims, durable idempotency, provider verification, and persistence. A state transition helper does not perform those checks or an external action.
+
+Publication validation includes the current deployment revision and active release so consumers can construct a compare-and-swap request. Publication status separately reports the current deployment revision, admission enablement and pause flags. `voiceAgentDisableRequestSchema` accepts only an Agent ID and expected revision; its response contract reports closed admission and preserved pause state. These schemas neither enable a deployment nor cancel existing calls.
+
+This package slice supports offline authoring, validation, and export. Generic Agent deployment and ordinary text create/update reject Voice; its dedicated publication path owns provider and runtime authorization. Importing these contracts requires no Voice settings, provider credentials, or database connection. They do not provision resources or enable phone calls.
+
+### Browser audio-read contract
+
+Import `voiceAudioReadRequestSchema`, `voiceAudioReadResponseSchema` and
+`voiceAudioCapabilitySchema` from `@sequenceholdings/agent-spec/voice-runs-audio`
+when validating Voice recording metadata in a browser. This narrow entry point
+avoids the Node-only compiler/hash exports at the package root. It defines
+metadata and delivery limits, not provider credentials or an audio transport.