@sequenceholdings/agent-spec 0.1.1

package/README.md

@@ -0,0 +1,39 @@
+# `@sequenceholdings/agent-spec`
+
+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.
+
+## Install
+
+```bash
+pnpm add @sequenceholdings/agent-spec
+```
+
+## Define an agent
+
+```ts
+import { defineAgent } from '@sequenceholdings/agent-spec'
+
+export const agent = defineAgent({
+  id: '680000000000000000000001',
+  name: 'Support Agent',
+  model: { provider: 'anthropic', name: 'claude-sonnet-4-6' },
+  systemPrompt: 'Help the support team investigate and resolve requests.',
+})
+```
+
+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`.
+
+## Exports
+
+- `@sequenceholdings/agent-spec` provides `defineAgent`,
+  `agentDefinitionSchema`, deterministic source formatting, and bundle hashing.
+- `@sequenceholdings/agent-spec/compiler` compiles `agent.ts` files and deploy
+  manifests in Node.js. It statically extracts literal definitions and never
+  imports or executes agent source.
+- `@sequenceholdings/agent-spec/yaml` provides `parseYamlAgent` only for
+  migrating legacy YAML definitions.

package/dist/compiler.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { type AgentDefinition } from './index.js';
+export declare const MAX_AGENT_FILES = 250;
+export declare const MAX_AGENT_SOURCE_BYTES = 1000000;
+export declare const agentDeployManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    definitions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        environments: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AgentDeployManifest = z.infer<typeof agentDeployManifestSchema>;
+export type SelectedAgentEntry = {
+    id: string;
+    path: string;
+};
+export declare function manifestEnvironments(manifest: AgentDeployManifest): Set<string>;
+export declare function assertKnownTargetEnvironment({ manifest, environment, deployEnvironments, }: {
+    manifest: AgentDeployManifest;
+    environment: string;
+    deployEnvironments?: readonly string[];
+}): void;
+export declare function selectionStats({ manifest, environment, }: {
+    manifest: AgentDeployManifest;
+    environment?: string;
+}): {
+    selected: number;
+    skipped: number;
+    total: number;
+};
+export declare function selectAgentEntries({ manifest, environment, }: {
+    manifest: AgentDeployManifest;
+    environment?: string;
+}): SelectedAgentEntry[];
+export interface CompiledAgentSource {
+    file: string;
+    definition: AgentDefinition;
+}
+export interface CompiledAgentBundle {
+    definitions: AgentDefinition[];
+    files: string[];
+    hash: string;
+    sources: CompiledAgentSource[];
+}
+export declare function compileAgentDirectory({ rootDir, filePaths, allowDuplicateIds, }: {
+    rootDir: string;
+    filePaths?: string[];
+    allowDuplicateIds?: boolean;
+}): Promise<CompiledAgentBundle>;

package/dist/compiler.js

@@ -0,0 +1,184 @@
+import { readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { agentDefinitionSchema, hashAgentBundle, } from './index.js';
+import { parseAgentSource } from './parse-agent-source.js';
+const objectIdPattern = /^[0-9a-f]{24}$/;
+export const MAX_AGENT_FILES = 250;
+export const MAX_AGENT_SOURCE_BYTES = 1_000_000;
+function isWithinRoot({ root, candidate, }) {
+    const relativePath = relative(root, candidate);
+    return (relativePath !== '..' &&
+        !relativePath.startsWith(`..${sep}`) &&
+        !isAbsolute(relativePath));
+}
+const manifestPathSchema = z
+    .string()
+    .min(1)
+    .refine((path) => !path.startsWith('/') &&
+    !path.split('/').some((segment) => segment === '..') &&
+    path.endsWith('/agent.ts'), 'definition path must be a relative agent.ts path without parent traversal');
+export const agentDeployManifestSchema = z.object({
+    schemaVersion: z.literal(1),
+    definitions: z.array(z.object({
+        id: z.string().regex(objectIdPattern),
+        path: manifestPathSchema,
+        environments: z.array(z.string().min(1)).min(1),
+    })),
+});
+export function manifestEnvironments(manifest) {
+    const names = new Set();
+    for (const entry of agentDeployManifestSchema.parse(manifest).definitions) {
+        for (const environment of entry.environments) {
+            if (environment !== '*')
+                names.add(environment);
+        }
+    }
+    return names;
+}
+export function assertKnownTargetEnvironment({ manifest, environment, deployEnvironments = [], }) {
+    const declared = manifestEnvironments(manifest);
+    if (declared.has(environment) || deployEnvironments.includes(environment)) {
+        return;
+    }
+    const known = [...new Set([...declared, ...deployEnvironments])].sort();
+    const { selected, skipped, total } = selectionStats({ manifest, environment });
+    if (skipped === 0)
+        return;
+    throw new Error(`Unknown target environment "${environment}": it is not a deployment ` +
+        `environment and no manifest entry declares it, so ${skipped} of ${total} ` +
+        `agents would be skipped and only the ${selected} wildcard entries ` +
+        `deployed. Known environments: ${known.join(', ')}.`);
+}
+export function selectionStats({ manifest, environment, }) {
+    const total = new Set(agentDeployManifestSchema.parse(manifest).definitions.map((e) => e.id)).size;
+    const selected = selectAgentEntries({ manifest, environment }).length;
+    return { selected, skipped: total - selected, total };
+}
+export function selectAgentEntries({ manifest, environment, }) {
+    const parsed = agentDeployManifestSchema.parse(manifest);
+    if (environment === undefined) {
+        const byPath = new Map();
+        for (const entry of parsed.definitions) {
+            byPath.set(entry.path, { id: entry.id, path: entry.path });
+        }
+        return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+    }
+    const selected = new Map();
+    for (const entry of parsed.definitions) {
+        if (entry.environments.includes('*') ||
+            entry.environments.includes(environment)) {
+            selected.set(entry.id, entry.path);
+        }
+    }
+    return [...selected.entries()]
+        .map(([id, path]) => ({ id, path }))
+        .sort((a, b) => a.path.localeCompare(b.path));
+}
+async function discoverAgentFiles(rootDir) {
+    const files = [];
+    async function walk(directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name !== 'node_modules' && entry.name !== 'dist') {
+                    await walk(path);
+                }
+            }
+            else if (entry.isFile() && entry.name === 'agent.ts') {
+                if (files.length >= MAX_AGENT_FILES) {
+                    throw new Error(`Agent source directory contains too many agent.ts files (maximum ${MAX_AGENT_FILES})`);
+                }
+                files.push(path);
+            }
+        }
+    }
+    await walk(rootDir);
+    return files;
+}
+async function resolveAgentFiles({ absoluteRoot, filePaths, }) {
+    if (filePaths.length > MAX_AGENT_FILES) {
+        throw new Error(`Agent source directory contains too many agent.ts files (maximum ${MAX_AGENT_FILES})`);
+    }
+    const files = await Promise.all(filePaths.map(async (path) => {
+        const requested = resolve(absoluteRoot, path);
+        if (!isWithinRoot({ root: absoluteRoot, candidate: requested })) {
+            throw new Error(`Agent source path escapes root: ${path}`);
+        }
+        const resolved = await realpath(requested);
+        if (!isWithinRoot({ root: absoluteRoot, candidate: resolved })) {
+            throw new Error(`Agent source path resolves outside root: ${path}`);
+        }
+        if (!(await stat(resolved)).isFile()) {
+            throw new Error(`Agent source path is not a file: ${path}`);
+        }
+        return resolved;
+    }));
+    return files.sort();
+}
+async function readAgentSource({ absoluteRoot, path, }) {
+    const resolved = await realpath(path);
+    if (!isWithinRoot({ root: absoluteRoot, candidate: resolved })) {
+        throw new Error(`Agent source path resolves outside root: ${path}`);
+    }
+    const metadata = await stat(resolved);
+    if (metadata.size > MAX_AGENT_SOURCE_BYTES) {
+        throw new Error(`Agent source ${relative(absoluteRoot, resolved)} exceeds the maximum size of ${MAX_AGENT_SOURCE_BYTES} bytes`);
+    }
+    return {
+        file: relative(absoluteRoot, resolved),
+        sourceText: await readFile(resolved, 'utf8'),
+    };
+}
+export async function compileAgentDirectory({ rootDir, filePaths, allowDuplicateIds = false, }) {
+    const absoluteRoot = await realpath(resolve(rootDir));
+    const files = filePaths === undefined
+        ? await discoverAgentFiles(absoluteRoot)
+        : await resolveAgentFiles({ absoluteRoot, filePaths });
+    if (files.length === 0) {
+        return {
+            definitions: [],
+            files: [],
+            hash: hashAgentBundle({ definitions: [] }),
+            sources: [],
+        };
+    }
+    const sources = [];
+    for (const absoluteFile of files) {
+        const { file, sourceText } = await readAgentSource({
+            absoluteRoot,
+            path: absoluteFile,
+        });
+        const exports = parseAgentSource({ fileName: file, sourceText });
+        for (const row of exports) {
+            try {
+                sources.push({
+                    file,
+                    definition: agentDefinitionSchema.parse(row.value),
+                });
+            }
+            catch (error) {
+                throw new Error(`Invalid agent export ${row.exportName} in ${file}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    if (!allowDuplicateIds) {
+        const ids = new Set();
+        for (const { definition, file } of sources) {
+            if (ids.has(definition.id)) {
+                throw new Error(`Duplicate agent id "${definition.id}" in ${file}`);
+            }
+            ids.add(definition.id);
+        }
+    }
+    const definitions = sources
+        .map((source) => source.definition)
+        .sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        definitions,
+        files: files.map((file) => relative(absoluteRoot, file)),
+        hash: hashAgentBundle({ definitions }),
+        sources,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+export type UnsupportedConstraint = {
+    path: string;
+    type: string;
+    keyword: string;
+};
+export declare function collectUnsupportedConstraints({ schema, path, }: {
+    schema: unknown;
+    path?: string;
+}): UnsupportedConstraint[];
+export declare const AGENT_PERMISSION_ROLES: readonly ["owner", "editor", "invoker", "outputs_viewer"];
+export type AgentPermissionRole = (typeof AGENT_PERMISSION_ROLES)[number];
+export declare const agentDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    framework: z.ZodOptional<z.ZodEnum<{
+        vercel: "vercel";
+        "claude-agent": "claude-agent";
+    }>>;
+    vmBackend: z.ZodOptional<z.ZodEnum<{
+        gce: "gce";
+        e2b: "e2b";
+    }>>;
+    idleTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    agentCapabilities: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    claudeToolSearch: z.ZodOptional<z.ZodEnum<{
+        enabled: "enabled";
+        disabled: "disabled";
+        auto: "auto";
+    }>>;
+    claudeBuiltInTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    openaiCodeInterpreter: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        containerId: z.ZodOptional<z.ZodString>;
+        fileIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>>;
+    model: z.ZodDefault<z.ZodObject<{
+        provider: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    thinking: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    reasoningEffort: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    temperature: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    mcpServers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    requiredMcpServers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    excludedMcpTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    hideIntermediateText: z.ZodOptional<z.ZodBoolean>;
+    middleware: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    subagents: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        forkContext: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>]>>>;
+    skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    contextFileIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    structuredOutput: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    inputSchema: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        fields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                enum: "enum";
+                text: "text";
+            }>;
+            required: z.ZodOptional<z.ZodBoolean>;
+            default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            placeholder: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    promptTemplate: z.ZodOptional<z.ZodString>;
+    webhooks: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    mcpServerConfigs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    aiCheckerConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    stubConfig: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    maxTtlSeconds: z.ZodOptional<z.ZodNumber>;
+    agentPermissions: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    apiPermissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    managedBy: z.ZodOptional<z.ZodNullable<z.ZodLiteral<"automation">>>;
+    isPublic: z.ZodOptional<z.ZodBoolean>;
+    publicOutputs: z.ZodOptional<z.ZodBoolean>;
+    permissions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            user: "user";
+            group: "group";
+        }>;
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            owner: "owner";
+            editor: "editor";
+            invoker: "invoker";
+            outputs_viewer: "outputs_viewer";
+        }>;
+    }, z.core.$strip>>>;
+}, z.core.$strict>;
+export type AgentDefinition = z.infer<typeof agentDefinitionSchema>;
+export type AgentDefinitionInput = z.input<typeof agentDefinitionSchema>;
+export declare function defineAgent(input: AgentDefinitionInput): AgentDefinition;
+export declare function canonicalJson(value: unknown): string;
+export declare function canonicalAgentJson(definition: AgentDefinition): string;
+export declare function hashAgentBundle({ definitions, }: {
+    definitions: AgentDefinition[];
+}): string;
+export declare function formatAgentSource({ definition, exportName, }: {
+    definition: unknown;
+    exportName?: string;
+}): string;
+export declare function generateAgentSource({ definition, exportName, }: {
+    definition: AgentDefinition;
+    exportName?: string;
+}): string;

package/dist/index.js

@@ -0,0 +1,248 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+const OBJECT_ID_PATTERN = /^[0-9a-f]{24}$/;
+const IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const DEFAULT_MODEL = {
+    provider: 'anthropic',
+    name: 'claude-sonnet-4-5-20250929',
+};
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+const unsupportedConstraints = {
+    integer: ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum'],
+    number: ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum'],
+    array: ['minItems', 'maxItems', 'uniqueItems'],
+    string: ['minLength', 'maxLength', 'format', 'pattern'],
+};
+export function collectUnsupportedConstraints({ schema, path = '', }) {
+    if (schema === null || typeof schema !== 'object')
+        return [];
+    const object = schema;
+    const type = typeof object.type === 'string' ? object.type : undefined;
+    const violations = [];
+    if (type !== undefined) {
+        for (const keyword of unsupportedConstraints[type] ?? []) {
+            if (keyword in object) {
+                violations.push({ path: path || '(root)', type, keyword });
+            }
+        }
+    }
+    if (type === 'object' &&
+        object.properties !== null &&
+        typeof object.properties === 'object') {
+        for (const [key, value] of Object.entries(object.properties)) {
+            violations.push(...collectUnsupportedConstraints({
+                schema: value,
+                path: `${path}.properties.${key}`,
+            }));
+        }
+    }
+    if (type === 'array' && object.items !== undefined) {
+        violations.push(...collectUnsupportedConstraints({
+            schema: object.items,
+            path: `${path}.items`,
+        }));
+    }
+    for (const combinator of ['anyOf', 'oneOf', 'allOf', 'prefixItems']) {
+        const entries = object[combinator];
+        if (!Array.isArray(entries))
+            continue;
+        entries.forEach((entry, index) => {
+            violations.push(...collectUnsupportedConstraints({
+                schema: entry,
+                path: `${path}.${combinator}[${index}]`,
+            }));
+        });
+    }
+    return violations;
+}
+const modelSchema = z.object({
+    provider: z.string().min(1),
+    name: z.string().min(1),
+});
+export const AGENT_PERMISSION_ROLES = [
+    'owner',
+    'editor',
+    'invoker',
+    'outputs_viewer',
+];
+const permissionGrantSchema = z.object({
+    type: z.enum(['user', 'group']),
+    id: z.string().min(1),
+    role: z.enum(AGENT_PERMISSION_ROLES),
+});
+const subagentSchema = z.union([
+    z.string().min(1),
+    z.object({
+        id: z.string().min(1),
+        forkContext: z.boolean().optional(),
+    }),
+]);
+const inputFieldSchema = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'name must be a valid identifier'),
+    label: z.string().optional(),
+    description: z.string().optional(),
+    type: z.enum(['string', 'text', 'number', 'boolean', 'enum']),
+    required: z.boolean().optional(),
+    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+    enum: z.array(z.string()).optional(),
+    placeholder: z.string().optional(),
+})
+    .superRefine((field, context) => {
+    if (field.type === 'enum') {
+        if (field.enum === undefined || field.enum.length === 0) {
+            context.addIssue({
+                code: 'custom',
+                path: ['enum'],
+                message: 'enum fields require at least one option',
+            });
+        }
+        if (field.default !== undefined &&
+            (typeof field.default !== 'string' ||
+                !field.enum?.includes(field.default))) {
+            context.addIssue({
+                code: 'custom',
+                path: ['default'],
+                message: 'default must be one of the declared enum options',
+            });
+        }
+        return;
+    }
+    if (field.default === undefined)
+        return;
+    const expected = field.type === 'number'
+        ? 'number'
+        : field.type === 'boolean'
+            ? 'boolean'
+            : 'string';
+    if (typeof field.default !== expected) {
+        context.addIssue({
+            code: 'custom',
+            path: ['default'],
+            message: `default for ${field.type} fields must be a ${expected}`,
+        });
+    }
+});
+const inputSchemaSchema = z
+    .object({ fields: z.array(inputFieldSchema) })
+    .refine((schema) => new Set(schema.fields.map((field) => field.name)).size ===
+    schema.fields.length, {
+    path: ['fields'],
+    message: 'fields[].name must be unique within an inputSchema',
+});
+const openaiCodeInterpreterSchema = z.preprocess((value) => {
+    if (value === true)
+        return { enabled: true };
+    if (value === false)
+        return { enabled: false };
+    return value;
+}, z.object({
+    enabled: z.boolean(),
+    containerId: z.string().min(1).optional(),
+    fileIds: z.array(z.string().min(1)).optional(),
+}));
+export const agentDefinitionSchema = z
+    .strictObject({
+    id: z
+        .string()
+        .regex(OBJECT_ID_PATTERN, 'id must be a 24-character lowercase hex ObjectId'),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    framework: z.enum(['vercel', 'claude-agent']).optional(),
+    vmBackend: z.enum(['gce', 'e2b']).optional(),
+    idleTimeoutSeconds: z.number().int().min(60).max(86_400).optional(),
+    agentCapabilities: jsonObjectSchema.nullish(),
+    claudeToolSearch: z.enum(['enabled', 'disabled', 'auto']).optional(),
+    claudeBuiltInTools: z.array(z.string()).default([]),
+    openaiCodeInterpreter: openaiCodeInterpreterSchema.nullish(),
+    model: modelSchema.default(DEFAULT_MODEL),
+    thinking: jsonObjectSchema.nullish(),
+    reasoningEffort: z.string().nullish(),
+    temperature: z.number().min(0).max(1).nullish(),
+    systemPrompt: z.string().optional(),
+    tools: z.array(z.string()).default([]),
+    mcpServers: z.array(z.string()).default([]),
+    requiredMcpServers: z.array(z.string()).default([]),
+    excludedMcpTools: z.array(z.string()).default([]),
+    hideIntermediateText: z.boolean().optional(),
+    middleware: z.array(z.string()).default([]),
+    subagents: z.array(subagentSchema).default([]),
+    skills: z.array(z.string()).default([]),
+    contextFileIds: z.array(z.string()).default([]),
+    structuredOutput: jsonObjectSchema.optional(),
+    inputSchema: inputSchemaSchema.nullish(),
+    promptTemplate: z.string().optional(),
+    webhooks: jsonObjectSchema.optional(),
+    mcpServerConfigs: jsonObjectSchema.optional(),
+    aiCheckerConfig: jsonObjectSchema.optional(),
+    stubConfig: jsonObjectSchema.nullish(),
+    maxTtlSeconds: z.number().int().positive().optional(),
+    agentPermissions: z.array(jsonObjectSchema).optional(),
+    apiPermissions: z.array(z.string()).optional(),
+    managedBy: z.literal('automation').nullish(),
+    isPublic: z.boolean().optional(),
+    publicOutputs: z.boolean().optional(),
+    permissions: z.array(permissionGrantSchema).optional(),
+})
+    .superRefine((definition, context) => {
+    for (const [index, serverId] of definition.requiredMcpServers.entries()) {
+        if (definition.mcpServers.includes(serverId))
+            continue;
+        context.addIssue({
+            code: 'custom',
+            path: ['requiredMcpServers', index],
+            message: `requiredMcpServers entry "${serverId}" must also appear in mcpServers`,
+        });
+    }
+    if (definition.structuredOutput?.enabled === true) {
+        const schema = definition.structuredOutput.schema;
+        for (const violation of collectUnsupportedConstraints({ schema })) {
+            context.addIssue({
+                code: 'custom',
+                path: ['structuredOutput', 'schema'],
+                message: `${violation.path}: "${violation.keyword}" on ${violation.type} is not supported`,
+            });
+        }
+    }
+});
+export function defineAgent(input) {
+    return agentDefinitionSchema.parse(input);
+}
+function sortJson(value) {
+    if (Array.isArray(value))
+        return value.map(sortJson);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const object = value;
+    return Object.fromEntries(Object.keys(object)
+        .sort()
+        .filter((key) => object[key] !== undefined)
+        .map((key) => [key, sortJson(object[key])]));
+}
+export function canonicalJson(value) {
+    return JSON.stringify(sortJson(value));
+}
+export function canonicalAgentJson(definition) {
+    return canonicalJson(definition);
+}
+export function hashAgentBundle({ definitions, }) {
+    const canonical = [...definitions]
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map(canonicalAgentJson)
+        .join('\n');
+    return createHash('sha256').update('sequence-agent-bundle-v1\0').update(canonical).digest('hex');
+}
+export function formatAgentSource({ definition, exportName = 'agent', }) {
+    if (!IDENTIFIER_PATTERN.test(exportName)) {
+        throw new Error('exportName must be a valid TypeScript identifier');
+    }
+    const object = JSON.stringify(sortJson(definition), null, 2);
+    return ("import { defineAgent } from '@sequenceholdings/agent-spec'\n\n" +
+        `export const ${exportName} = defineAgent(${object})\n`);
+}
+export function generateAgentSource({ definition, exportName = 'agent', }) {
+    return formatAgentSource({ definition: defineAgent(definition), exportName });
+}

package/dist/parse-agent-source.d.ts

@@ -0,0 +1,10 @@
+import ts from 'typescript';
+export type ParsedAgentExport = {
+    exportName: string;
+    literalNode: ts.ObjectLiteralExpression;
+    value: unknown;
+};
+export declare function parseAgentSource({ fileName, sourceText, }: {
+    fileName: string;
+    sourceText: string;
+}): ParsedAgentExport[];

package/dist/parse-agent-source.js

@@ -0,0 +1,181 @@
+import ts from 'typescript';
+export function parseAgentSource({ fileName, sourceText, }) {
+    const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const parseDiagnostics = sourceFile.parseDiagnostics ?? [];
+    const parseErrors = parseDiagnostics.filter((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error);
+    if (parseErrors.length > 0) {
+        const first = parseErrors[0];
+        const message = first
+            ? ts.flattenDiagnosticMessageText(first.messageText, '\n')
+            : 'unknown parse error';
+        throw new Error(`${fileName}: invalid TypeScript — ${message}`);
+    }
+    const bindings = collectConstObjectBindings(sourceFile);
+    const found = [];
+    const seenLiterals = new Set();
+    const take = ({ exportName, expression, }) => {
+        const literal = resolveObjectLiteral(expression, bindings);
+        if (!literal) {
+            throw new Error(`${fileName}: export "${exportName}" must be a defineAgent({...}) ` +
+                `call or an object literal — executable expressions are not allowed`);
+        }
+        if (seenLiterals.has(literal))
+            return;
+        seenLiterals.add(literal);
+        found.push({
+            exportName,
+            literalNode: literal,
+            value: objectLiteralToValue(literal, fileName),
+        });
+    };
+    for (const statement of sourceFile.statements) {
+        if (ts.isVariableStatement(statement)) {
+            const isExport = statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+            if (!isExport)
+                continue;
+            for (const declaration of statement.declarationList.declarations) {
+                if (!ts.isIdentifier(declaration.name) || !declaration.initializer) {
+                    continue;
+                }
+                take({
+                    exportName: declaration.name.text,
+                    expression: declaration.initializer,
+                });
+            }
+            continue;
+        }
+        if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+            take({ exportName: 'default', expression: statement.expression });
+            continue;
+        }
+        if (ts.isExportDeclaration(statement) && statement.exportClause) {
+            if (!ts.isNamedExports(statement.exportClause))
+                continue;
+            for (const element of statement.exportClause.elements) {
+                const localName = (element.propertyName ?? element.name).text;
+                const binding = bindings.get(localName);
+                if (!binding) {
+                    throw new Error(`${fileName}: export "${element.name.text}" does not resolve to ` +
+                        `a local object literal`);
+                }
+                take({ exportName: element.name.text, expression: binding });
+            }
+        }
+    }
+    if (found.length === 0) {
+        throw new Error(`${fileName}: no agent definition export found (expected ` +
+            `export const agent = defineAgent({...}) or an object literal)`);
+    }
+    return found;
+}
+function collectConstObjectBindings(sourceFile) {
+    const bindings = new Map();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || !declaration.initializer) {
+                continue;
+            }
+            const literal = unwrapDefineAgent(declaration.initializer);
+            if (literal)
+                bindings.set(declaration.name.text, literal);
+        }
+    }
+    return bindings;
+}
+function resolveObjectLiteral(expression, bindings) {
+    const unwrapped = unwrapDefineAgent(expression);
+    if (unwrapped)
+        return unwrapped;
+    if (ts.isIdentifier(expression))
+        return bindings.get(expression.text);
+    return undefined;
+}
+function unwrapDefineAgent(expression) {
+    if (ts.isObjectLiteralExpression(expression))
+        return expression;
+    if (ts.isCallExpression(expression) &&
+        ts.isIdentifier(expression.expression) &&
+        expression.expression.text === 'defineAgent' &&
+        expression.arguments.length === 1) {
+        const arg = expression.arguments[0];
+        if (arg && ts.isObjectLiteralExpression(arg))
+            return arg;
+    }
+    if (ts.isAsExpression(expression) ||
+        ts.isSatisfiesExpression(expression) ||
+        ts.isParenthesizedExpression(expression)) {
+        return unwrapDefineAgent(expression.expression);
+    }
+    return undefined;
+}
+function objectLiteralToValue(literal, fileName) {
+    const result = {};
+    for (const property of literal.properties) {
+        if (ts.isSpreadAssignment(property)) {
+            const spread = expressionToValue(property.expression, fileName);
+            if (!spread || typeof spread !== 'object' || Array.isArray(spread)) {
+                throw new Error(`${fileName}: object spreads must be object literals`);
+            }
+            Object.assign(result, spread);
+            continue;
+        }
+        if (!ts.isPropertyAssignment(property)) {
+            throw new Error(`${fileName}: only data properties are allowed in agent definitions ` +
+                `(no methods, getters, or shorthand)`);
+        }
+        const key = propertyNameText(property.name, fileName);
+        result[key] = expressionToValue(property.initializer, fileName);
+    }
+    return result;
+}
+function propertyNameText(name, fileName) {
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) {
+        return name.text;
+    }
+    throw new Error(`${fileName}: computed property names are not allowed`);
+}
+function expressionToValue(expression, fileName) {
+    expression = unwrapExpression(expression);
+    if (ts.isStringLiteralLike(expression))
+        return expression.text;
+    if (ts.isNumericLiteral(expression))
+        return Number(expression.text);
+    if (expression.kind === ts.SyntaxKind.TrueKeyword)
+        return true;
+    if (expression.kind === ts.SyntaxKind.FalseKeyword)
+        return false;
+    if (expression.kind === ts.SyntaxKind.NullKeyword)
+        return null;
+    if (ts.isPrefixUnaryExpression(expression) &&
+        expression.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(expression.operand)) {
+        return -Number(expression.operand.text);
+    }
+    if (ts.isObjectLiteralExpression(expression)) {
+        return objectLiteralToValue(expression, fileName);
+    }
+    if (ts.isArrayLiteralExpression(expression)) {
+        return expression.elements.flatMap((element) => {
+            if (ts.isSpreadElement(element)) {
+                const spread = expressionToValue(element.expression, fileName);
+                if (!Array.isArray(spread)) {
+                    throw new Error(`${fileName}: array spreads must be array literals`);
+                }
+                return spread;
+            }
+            return [expressionToValue(element, fileName)];
+        });
+    }
+    throw new Error(`${fileName}: agent definitions must be pure data literals ` +
+        `(found ${ts.SyntaxKind[expression.kind]})`);
+}
+function unwrapExpression(expression) {
+    while (ts.isAsExpression(expression) ||
+        ts.isSatisfiesExpression(expression) ||
+        ts.isParenthesizedExpression(expression)) {
+        expression = expression.expression;
+    }
+    return expression;
+}

package/dist/yaml.d.ts

@@ -0,0 +1,6 @@
+import { type AgentDefinition } from './index.js';
+export declare const MAX_YAML_BYTES = 1000000;
+export declare function parseYamlAgent({ yamlContent, filename, }: {
+    yamlContent: string;
+    filename: string;
+}): AgentDefinition;

package/dist/yaml.js

@@ -0,0 +1,29 @@
+import { JSON_SCHEMA, load as loadYaml } from 'js-yaml';
+import { z } from 'zod';
+import { agentDefinitionSchema } from './index.js';
+export const MAX_YAML_BYTES = 1_000_000;
+export function parseYamlAgent({ yamlContent, filename, }) {
+    if (Buffer.byteLength(yamlContent, 'utf8') > MAX_YAML_BYTES) {
+        throw new Error(`Invalid YAML in ${filename}: content exceeds the maximum size of ${MAX_YAML_BYTES} bytes`);
+    }
+    const sourceWithStringId = yamlContent.replace(/^(\s*id:\s*)([0-9a-f]{24})(\s*(?:#.*)?)$/m, '$1"$2"$3');
+    const parsed = loadYaml(sourceWithStringId, {
+        schema: JSON_SCHEMA,
+    });
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Invalid YAML in ${filename}: expected an object`);
+    }
+    const input = Object.fromEntries(Object.entries(parsed));
+    try {
+        return agentDefinitionSchema.parse(input);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const issues = error.issues
+                .map((issue) => `${issue.path.join('.') || '(root)'} — ${issue.message}`)
+                .join('; ');
+            throw new Error(`Invalid YAML in ${filename}: ${issues}`);
+        }
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@sequenceholdings/agent-spec",
+  "version": "0.1.1",
+  "description": "Typed agent definition contract, compiler, hashing, and migration utilities",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sequenceholdings/studio.git",
+    "directory": "shared/services/agent-spec"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./compiler": {
+      "types": "./dist/compiler.d.ts",
+      "import": "./dist/compiler.js",
+      "default": "./dist/compiler.js"
+    },
+    "./yaml": {
+      "types": "./dist/yaml.d.ts",
+      "import": "./dist/yaml.js",
+      "default": "./dist/yaml.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "js-yaml": "^4.1.1",
+    "typescript": "^5.6.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "vitest": "^4.1.5"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "agents",
+    "spec",
+    "zod"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:package": "pnpm run build && pnpm run type-check && pnpm run test && node scripts/check-package.mjs",
+    "test:watch": "vitest"
+  }
+}