@sequenceholdings/agent-spec 0.1.2 → 0.1.4

package/dist/index.js

@@ -1,247 +1,4 @@
-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(),
-    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 });
-}
+export * from './agent-definition.js';
+export * from './voice.js';
+export * from './job-request-hash.js';
+export * from './client-proposals.js';

package/dist/input-schema.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export declare const inputSchemaSchema: 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";
+            text: "text";
+            enum: "enum";
+        }>;
+        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>;

package/dist/input-schema.js

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+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}`,
+        });
+    }
+});
+export 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',
+});

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-access.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { type VoiceScope } from './voice-common.js';
+export declare const voiceParticipantPolicySchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    environmentId: z.ZodString;
+    revision: z.ZodNumber;
+    participantPrincipalIds: z.ZodArray<z.ZodString>;
+    operatorPrincipalIds: z.ZodArray<z.ZodString>;
+    updatedByPrincipalId: z.ZodString;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type VoiceParticipantPolicy = z.infer<typeof voiceParticipantPolicySchema>;
+export declare function isVoiceContextEligible({ featureEnabled, scope, eligibleScope }: {
+    featureEnabled: boolean;
+    scope: VoiceScope;
+    eligibleScope: unknown;
+}): boolean;
+export declare const voiceOutboundDestinationSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    environmentId: z.ZodString;
+    destinationId: z.ZodString;
+    staffPrincipalId: z.ZodString;
+    phoneNumberE164: z.ZodString;
+    registeredByPrincipalId: z.ZodString;
+    verifiedAt: z.ZodISODateTime;
+    enabled: z.ZodBoolean;
+}, z.core.$strict>;
+export type VoiceOutboundDestination = z.infer<typeof voiceOutboundDestinationSchema>;
+export declare const voiceEnvironmentBindingsSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    environmentId: z.ZodString;
+    runtimeAccountId: z.ZodString;
+    syntheticNamespaceRef: z.ZodString;
+    elevenLabsWorkspaceId: z.ZodString;
+    elevenLabsCredentialRef: z.ZodString;
+    twilioSubaccountSid: z.ZodString;
+    twilioCredentialRef: z.ZodString;
+    twilioRecordingEnabled: z.ZodLiteral<false>;
+}, z.core.$strict>;
+export type VoiceEnvironmentBindings = z.infer<typeof voiceEnvironmentBindingsSchema>;

package/dist/voice-access.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { voiceIdSchema, voiceRevisionSchema, voiceScopeSchema, voiceTimestampSchema } from './voice-common.js';
+const principalIdsSchema = z.array(voiceIdSchema).max(200)
+    .refine((ids) => new Set(ids).size === ids.length, 'Duplicate principal ID');
+export const voiceParticipantPolicySchema = voiceScopeSchema.extend({
+    revision: voiceRevisionSchema,
+    participantPrincipalIds: principalIdsSchema,
+    operatorPrincipalIds: principalIdsSchema,
+    updatedByPrincipalId: voiceIdSchema,
+    updatedAt: voiceTimestampSchema,
+}).refine((policy) => policy.operatorPrincipalIds.every((id) => policy.participantPrincipalIds.includes(id)), { path: ['operatorPrincipalIds'], message: 'Operators must also be explicit participants' });
+export function isVoiceContextEligible({ featureEnabled, scope, eligibleScope }) {
+    if (!featureEnabled)
+        return false;
+    const parsed = voiceScopeSchema.safeParse(eligibleScope);
+    return parsed.success && parsed.data.tenantId === scope.tenantId && parsed.data.environmentId === scope.environmentId;
+}
+export const voiceOutboundDestinationSchema = voiceScopeSchema.extend({
+    destinationId: voiceIdSchema,
+    staffPrincipalId: voiceIdSchema,
+    phoneNumberE164: z.string().regex(/^\+[1-9]\d{1,14}$/),
+    registeredByPrincipalId: voiceIdSchema,
+    verifiedAt: voiceTimestampSchema,
+    enabled: z.boolean(),
+});
+export const voiceEnvironmentBindingsSchema = voiceScopeSchema.extend({
+    runtimeAccountId: voiceIdSchema,
+    syntheticNamespaceRef: voiceIdSchema,
+    elevenLabsWorkspaceId: voiceIdSchema,
+    elevenLabsCredentialRef: voiceIdSchema,
+    twilioSubaccountSid: voiceIdSchema,
+    twilioCredentialRef: voiceIdSchema,
+    twilioRecordingEnabled: z.literal(false),
+});