@sequenceholdings/agent-spec 0.1.1 → 0.1.3

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,40 @@ 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`).
+
 ## Exports
 
 - `@sequenceholdings/agent-spec` provides `defineAgent`,
@@ -37,3 +77,56 @@ 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.
+
+## 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.