@agentpulselabs/cli-plugin-pulse 0.1.0 → 1.0.0

package/src/lib/intents.js

@@ -0,0 +1,590 @@
+import { assertNever, HubError } from './errors.js';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const OPAQUE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const FORBIDDEN_FIELDS = new Set([
+  'command', 'content', 'credential', 'cwd', 'env', 'exec', 'executable',
+  'privatekey', 'prompt', 'script', 'source', 'shell', 'socket', 'stderr',
+  'stdout', 'token', 'transcript',
+]);
+const SECRET_VALUE = /(?:-----BEGIN [A-Z ]*PRIVATE KEY-----|(?:api[_-]?key|access[_-]?token|client[_-]?secret|password)\s*[:=]\s*\S+)/i;
+const RESULT_FIELDS = Object.freeze({
+  'delivery.plan': ['plan', 'planDigest'],
+  'workspace.inspect': ['summary', 'repo', 'fileManifestHash'],
+  'worktree.create': ['summary', 'branch', 'worktreeRef', 'repoHash'],
+  'git.inspect': ['summary', 'status', 'diffSummaryHash'],
+  'agent.start': ['summary', 'agentSessionRefHash'],
+  'agent.turn': ['summary', 'usage', 'evidenceIds', 'needsUser', 'decision', 'decisionDigest'],
+  'agent.stop': ['summary', 'stopped'],
+  'evidence.collect': ['summary', 'artifacts'],
+  'hub.chat.post': ['outcome', 'summary'],
+  'hub.nudge': ['outcome', 'summary'],
+  'hub.decision': ['outcome', 'summary'],
+  'hub.accept': ['outcome', 'summary'],
+  'hub.bus.reply': ['outcome', 'summary'],
+  'hub.status.set': ['outcome', 'summary'],
+});
+/** What a hub action did, as the cloud stores it; the same set the cloud's jobSchemas accepts. */
+export const HUB_OUTCOMES = Object.freeze(['posted', 'sent', 'queued', 'recorded', 'accepted', 'replied']);
+/** The local hub's own write limits (agents-hub/server/http.mjs), so a job never carries text the hub would cut. */
+export const HUB_TEXT_LIMITS = Object.freeze({ chat: 4000, nudge: 500, decision: 4000, acceptNote: 500, busReply: 4000, statusReason: 500, statusTo: 120 });
+/** The statuses a person sets by hand on a delivery or an agent (agents-hub lib/status.mjs). */
+export const HUB_STATUSES = Object.freeze(['done', 'blocked', 'stopped', 'handed-over', 'working']);
+/** The Board's step columns, as a card moved to one names it (agents-hub lib/status.mjs STEP_IDS). */
+export const HUB_STEPS = Object.freeze(['research', 'design', 'mockup', 'build', 'review', 'checks', 'proof']);
+const HUB_CHANNEL = /^(?:task:[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+|project:[^\0\n]{1,200}|dm:[A-Za-z0-9][A-Za-z0-9._:@-]{0,199})$/;
+const HUB_CHANNEL_MAX = 209;
+const HUB_STREAM_KEY = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+const HUB_LOCAL_ID = /^[^\0\n]{1,200}$/;
+const HUB_TARGET_ID = /^[^\0-\x1f\x7f]{1,100}$/;
+const ARTIFACT_KINDS = new Set([
+  'plan', 'summary', 'check_result', 'screenshot', 'diff_summary', 'file_manifest', 'review',
+]);
+const ARTIFACT_STORAGE = new Set(['inline_redacted', 'signed_reference', 'local_only']);
+
+export const INTENT_KINDS = Object.freeze([
+  'workspace.read',
+  'workspace.write',
+  'git.read',
+  'git.write',
+  'worktree.create',
+  'agent.cursor.invoke',
+  'agent.claude.invoke',
+  'hub.write',
+]);
+
+export const HUB_JOB_TYPES = Object.freeze(['hub.chat.post', 'hub.nudge', 'hub.decision', 'hub.accept', 'hub.bus.reply', 'hub.status.set']);
+
+export const JOB_TYPES = Object.freeze([
+  'delivery.plan',
+  'workspace.inspect',
+  'worktree.create',
+  'git.inspect',
+  'agent.start',
+  'agent.turn',
+  'agent.stop',
+  'evidence.collect',
+  ...HUB_JOB_TYPES,
+]);
+
+const JOB_SCHEMAS = Object.freeze({
+  'delivery.plan': {
+    required: ['description', 'rootIds', 'budget'],
+    allowed: ['description', 'rootIds', 'budget'],
+  },
+  'workspace.inspect': {
+    required: ['rootId'],
+    allowed: ['rootId', 'includeGit'],
+  },
+  'worktree.create': {
+    required: ['rootId', 'branch', 'worktreeRef'],
+    allowed: ['rootId', 'branch', 'worktreeRef'],
+  },
+  'git.inspect': {
+    required: ['rootId'],
+    allowed: ['rootId', 'ref', 'includeDiffSummary'],
+  },
+  'agent.start': {
+    required: ['agentId', 'rootId', 'provider', 'model', 'role', 'intent'],
+    allowed: ['agentId', 'rootId', 'provider', 'model', 'role', 'intent', 'budget'],
+  },
+  'agent.turn': {
+    required: ['agentSessionId', 'rootId', 'intent'],
+    allowed: ['agentSessionId', 'rootId', 'intent', 'budget'],
+  },
+  'agent.stop': {
+    required: ['agentSessionId', 'rootId', 'reason'],
+    allowed: ['agentSessionId', 'rootId', 'reason'],
+  },
+  'evidence.collect': {
+    required: ['rootId', 'kinds'],
+    allowed: ['rootId', 'kinds', 'maxBytes'],
+  },
+  'hub.chat.post': { required: ['ch', 'text'], allowed: ['ch', 'text'] },
+  'hub.nudge': { required: ['to', 'type', 'text'], allowed: ['to', 'type', 'text'] },
+  'hub.decision': { required: ['key', 'kind', 'text'], allowed: ['key', 'kind', 'text', 'ref'] },
+  'hub.accept': { required: ['delivery'], allowed: ['delivery', 'note'] },
+  'hub.bus.reply': { required: ['id', 'text'], allowed: ['id', 'text'] },
+  'hub.status.set': { required: ['target'], allowed: ['target', 'status', 'reason', 'to', 'step'] },
+});
+
+function inputError(message) {
+  return new HubError('invalid_job_arguments', message);
+}
+
+function assertNoAuthorityExpansion(value) {
+  if (!value || typeof value !== 'object') return;
+  if (Array.isArray(value)) {
+    value.forEach(assertNoAuthorityExpansion);
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    if (FORBIDDEN_FIELDS.has(key.toLowerCase())) {
+      throw inputError(`Field "${key}" is not permitted`);
+    }
+    assertNoAuthorityExpansion(entry);
+  }
+}
+
+function assertSafeCloudValue(value) {
+  if (typeof value === 'string') {
+    if (SECRET_VALUE.test(value)) throw inputError('Cloud value appears to contain secret material');
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  if (Array.isArray(value)) {
+    value.forEach(assertSafeCloudValue);
+    return;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    if (FORBIDDEN_FIELDS.has(key.toLowerCase())) {
+      throw inputError(`Field "${key}" is not permitted in cloud storage`);
+    }
+    assertSafeCloudValue(entry);
+  }
+}
+
+function assertString(value, name, maximum, { optional = false } = {}) {
+  if (optional && value === undefined) return;
+  if (typeof value !== 'string' || !value.trim() || value.length > maximum || value.includes('\0')) {
+    throw inputError(`${name} must be a bounded non-empty string`);
+  }
+}
+
+function assertRootId(value) {
+  assertString(value, 'rootId', 80);
+  if (
+    !OPAQUE_ID.test(value) ||
+    value === '.' ||
+    value === '..' ||
+    value.includes('..') ||
+    value.startsWith('/')
+  ) {
+    throw inputError('rootId must be an opaque identifier, not a path');
+  }
+}
+
+function assertLocalId(value, name, maximum = 200) {
+  if (typeof value !== 'string' || !HUB_LOCAL_ID.test(value) || value.trim() !== value || value.length > maximum) {
+    throw inputError(`${name} must be a local hub id`);
+  }
+}
+
+function assertUuid(value, name) {
+  if (!UUID.test(String(value || ''))) throw inputError(`${name} must be a UUID`);
+}
+
+function assertBudget(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw inputError('budget is required');
+  }
+  const allowed = new Set(['maxTokens', 'maxCostUsd', 'maxWallMs', 'maxOutputBytes']);
+  for (const [key, amount] of Object.entries(value)) {
+    if (!allowed.has(key) || !Number.isFinite(amount) || amount <= 0) {
+      throw inputError(`budget.${key} is invalid`);
+    }
+  }
+  if (Object.keys(value).length === 0) throw inputError('budget requires explicit limits');
+}
+
+function assertStructuredIntent(intent) {
+  if (!intent || typeof intent !== 'object' || Array.isArray(intent)) {
+    throw inputError('intent must be a structured object');
+  }
+  const allowed = new Set(['kind', 'subjectId', 'subjectVersion', 'subjectDigest', 'outcome']);
+  if (Object.keys(intent).some((field) => !allowed.has(field))) {
+    throw inputError('intent contains an unsupported field');
+  }
+  if (!['delivery_task', 'decision_response', 'status_request', 'resume'].includes(intent.kind)) {
+    throw inputError('intent kind is invalid');
+  }
+  assertUuid(intent.subjectId, 'intent.subjectId');
+  if (!Number.isInteger(intent.subjectVersion) || intent.subjectVersion < 1) {
+    throw inputError('intent.subjectVersion must be positive');
+  }
+  if (!SHA256.test(String(intent.subjectDigest || ''))) {
+    throw inputError('intent.subjectDigest must be SHA-256 hex');
+  }
+  if (intent.kind === 'decision_response') {
+    if (
+      !intent.outcome ||
+      typeof intent.outcome !== 'object' ||
+      Array.isArray(intent.outcome) ||
+      Object.keys(intent.outcome).some(
+        (key) => !['optionId', 'label', 'impact', 'decision'].includes(key)
+      )
+    ) {
+      throw inputError('decision response requires a bounded outcome');
+    }
+    assertString(intent.outcome.optionId, 'intent.outcome.optionId', 80);
+    assertString(intent.outcome.label, 'intent.outcome.label', 240);
+    assertString(intent.outcome.impact, 'intent.outcome.impact', 1000, { optional: true });
+    if (!['approved', 'rejected'].includes(intent.outcome.decision)) {
+      throw inputError('intent.outcome.decision is invalid');
+    }
+  } else if (intent.outcome !== undefined) {
+    throw inputError('intent outcome is only allowed for decision responses');
+  }
+}
+
+function validateArguments(type, args) {
+  const schema = JOB_SCHEMAS[type];
+  if (!schema) throw inputError(`Unsupported job type "${type}"`);
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    throw inputError('arguments must be an object');
+  }
+  if (Buffer.byteLength(JSON.stringify(args), 'utf8') > 64 * 1024) {
+    throw inputError('arguments exceed 64 KiB');
+  }
+  for (const required of schema.required) {
+    if (args[required] === undefined || args[required] === null) {
+      throw inputError(`${required} is required`);
+    }
+  }
+  for (const field of Object.keys(args)) {
+    if (!schema.allowed.includes(field)) {
+      throw inputError(`Field "${field}" is not allowed for ${type}`);
+    }
+  }
+  assertNoAuthorityExpansion(args);
+  switch (type) {
+    case 'delivery.plan':
+      assertString(args.description, 'description', 8_000);
+      if (!Array.isArray(args.rootIds) || args.rootIds.length < 1 || args.rootIds.length > 32) {
+        throw inputError('rootIds must contain 1 to 32 approved roots');
+      }
+      args.rootIds.forEach(assertRootId);
+      assertBudget(args.budget);
+      break;
+    case 'workspace.inspect':
+      assertRootId(args.rootId);
+      if (args.includeGit !== undefined && typeof args.includeGit !== 'boolean') {
+        throw inputError('includeGit must be boolean');
+      }
+      break;
+    case 'worktree.create':
+      assertRootId(args.rootId);
+      assertString(args.branch, 'branch', 180);
+      assertString(args.worktreeRef, 'worktreeRef', 180);
+      break;
+    case 'git.inspect':
+      assertRootId(args.rootId);
+      assertString(args.ref, 'ref', 180, { optional: true });
+      if (args.includeDiffSummary !== undefined && typeof args.includeDiffSummary !== 'boolean') {
+        throw inputError('includeDiffSummary must be boolean');
+      }
+      break;
+    case 'agent.start':
+      assertUuid(args.agentId, 'agentId');
+      assertRootId(args.rootId);
+      assertString(args.provider, 'provider', 40);
+      assertString(args.model, 'model', 100);
+      if (!['architect', 'coder', 'reviewer', 'auditor'].includes(args.role)) {
+        throw inputError('role is invalid');
+      }
+      assertStructuredIntent(args.intent);
+      if (args.budget !== undefined) assertBudget(args.budget);
+      break;
+    case 'agent.turn':
+      assertUuid(args.agentSessionId, 'agentSessionId');
+      assertRootId(args.rootId);
+      assertStructuredIntent(args.intent);
+      if (args.budget !== undefined) assertBudget(args.budget);
+      break;
+    case 'agent.stop':
+      assertUuid(args.agentSessionId, 'agentSessionId');
+      assertRootId(args.rootId);
+      assertString(args.reason, 'reason', 240);
+      break;
+    case 'evidence.collect':
+      assertRootId(args.rootId);
+      if (!Array.isArray(args.kinds) || args.kinds.length < 1 || args.kinds.length > 8) {
+        throw inputError('kinds must contain 1 to 8 entries');
+      }
+      for (const kind of args.kinds) {
+        if (!['check_result', 'screenshot', 'diff_summary', 'file_manifest', 'review'].includes(kind)) {
+          throw inputError(`Unsupported evidence kind "${kind}"`);
+        }
+      }
+      if (
+        args.maxBytes !== undefined &&
+        (!Number.isInteger(args.maxBytes) || args.maxBytes < 1 || args.maxBytes > 1_048_576)
+      ) {
+        throw inputError('maxBytes is outside the allowed range');
+      }
+      break;
+    case 'hub.chat.post':
+      if (typeof args.ch !== 'string' || args.ch.length > HUB_CHANNEL_MAX || !HUB_CHANNEL.test(args.ch)) {
+        throw inputError('ch must be a task:, project: or dm: channel id');
+      }
+      assertString(args.text, 'text', HUB_TEXT_LIMITS.chat);
+      break;
+    case 'hub.nudge':
+      if (!Array.isArray(args.to) || args.to.length < 1 || args.to.length > 50) throw inputError('to must contain 1 to 50 agent ids');
+      for (const id of args.to) assertLocalId(id, 'to[]');
+      if (new Set(args.to).size !== args.to.length) throw inputError('to must not repeat an agent');
+      if (!['NUDGE', 'STATUS?'].includes(args.type)) throw inputError('type must be NUDGE or STATUS?');
+      assertString(args.text, 'text', HUB_TEXT_LIMITS.nudge);
+      break;
+    case 'hub.decision':
+      if (typeof args.key !== 'string' || !HUB_STREAM_KEY.test(args.key)) throw inputError('key must be a <repo>/<channel> stream key');
+      if (!['DECISION', 'CHANGES REQUESTED'].includes(args.kind)) throw inputError('kind must be DECISION or CHANGES REQUESTED');
+      assertString(args.text, 'text', HUB_TEXT_LIMITS.decision);
+      if (args.ref !== undefined) assertLocalId(args.ref, 'ref');
+      break;
+    case 'hub.accept':
+      assertLocalId(args.delivery, 'delivery', 100);
+      assertString(args.note, 'note', HUB_TEXT_LIMITS.acceptNote, { optional: true });
+      break;
+    case 'hub.bus.reply':
+      assertLocalId(args.id, 'id');
+      assertString(args.text, 'text', HUB_TEXT_LIMITS.busReply);
+      break;
+    case 'hub.status.set': {
+      const { target } = args;
+      if (!target || typeof target !== 'object' || Array.isArray(target) || Object.keys(target).some((key) => !['kind', 'id'].includes(key))) {
+        throw inputError('target must be { kind, id }');
+      }
+      if (target.kind === 'stream') {
+        if (typeof target.id !== 'string' || target.id.length > 240 || !HUB_STREAM_KEY.test(target.id)) throw inputError('target.id must be a <repo>/<channel> stream key');
+        if (!HUB_STEPS.includes(args.step)) throw inputError(`step must be one of ${HUB_STEPS.join(', ')}`);
+        const extra = Object.keys(args).find((key) => !['target', 'step'].includes(key));
+        if (extra) throw inputError(`${extra} is not part of a move`);
+        break;
+      }
+      if (args.step !== undefined) throw inputError('step is only for a stream');
+      if (!['delivery', 'agent'].includes(target.kind)) throw inputError('target.kind must be delivery, agent or stream');
+      if (typeof target.id !== 'string' || !HUB_TARGET_ID.test(target.id)) throw inputError('target.id must be a local hub id of at most 100 characters');
+      if (!HUB_STATUSES.includes(args.status)) throw inputError(`status must be one of ${HUB_STATUSES.join(', ')}`);
+      assertString(args.reason, 'reason', HUB_TEXT_LIMITS.statusReason, { optional: args.status !== 'blocked' });
+      if (args.status === 'handed-over') assertString(args.to, 'to', HUB_TEXT_LIMITS.statusTo);
+      else if (args.to !== undefined) throw inputError('to is only for handed-over');
+      break;
+    }
+    default:
+      assertNever(type, 'job type');
+  }
+  return structuredClone(args);
+}
+
+function expectedCapability(type, args, sessionProvider) {
+  switch (type) {
+    case 'delivery.plan':
+    case 'workspace.inspect':
+    case 'evidence.collect':
+      return 'workspace.read';
+    case 'worktree.create':
+      return 'worktree.create';
+    case 'git.inspect':
+      return 'git.read';
+    case 'agent.start':
+      return `agent.${args.provider}.invoke`;
+    case 'agent.turn':
+    case 'agent.stop':
+      if (!sessionProvider) throw inputError('session provider is required');
+      return `agent.${sessionProvider}.invoke`;
+    case 'hub.chat.post':
+    case 'hub.nudge':
+    case 'hub.decision':
+    case 'hub.accept':
+    case 'hub.bus.reply':
+    case 'hub.status.set':
+      return 'hub.write';
+    default:
+      return assertNever(type, 'job type');
+  }
+}
+
+export function validateIntent(job, policy, { sessionProvider = null } = {}) {
+  const allowedJobFields = new Set([
+    'type', 'capability', 'rootId', 'arguments', 'policyVersion', 'idempotencyKey',
+  ]);
+  if (!job || typeof job !== 'object' || Array.isArray(job)) throw inputError('job must be an object');
+  if (Object.keys(job).some((field) => !allowedJobFields.has(field))) {
+    throw inputError('job contains an unsupported field');
+  }
+  if (!JOB_TYPES.includes(job.type)) throw inputError(`Unsupported job type "${job.type}"`);
+  if (!Number.isInteger(job.policyVersion) || job.policyVersion !== policy.version) {
+    throw new HubError('HUB_POLICY_STALE', 'Job policy version does not match the local grant');
+  }
+  if (
+    typeof job.idempotencyKey !== 'string' ||
+    job.idempotencyKey.length < 1 ||
+    job.idempotencyKey.length > 128
+  ) {
+    throw inputError('idempotencyKey is required and bounded');
+  }
+  const args = validateArguments(job.type, job.arguments);
+  const capability = expectedCapability(job.type, args, sessionProvider);
+  if (job.capability !== capability || !INTENT_KINDS.includes(capability)) {
+    throw new HubError('HUB_CAPABILITY_DENIED', 'Job capability does not match its registered type');
+  }
+  if (!policy.capabilities.includes(capability)) {
+    throw new HubError('HUB_CAPABILITY_DENIED', `Capability is not granted: ${capability}`);
+  }
+  const rootIds = args.rootIds || (args.rootId ? [args.rootId] : []);
+  if (rootIds.some((rootId) => !policy.rootIds.includes(rootId))) {
+    throw new HubError('HUB_CAPABILITY_DENIED', 'Job references an unapproved root');
+  }
+  if (job.rootId !== undefined && args.rootId !== undefined && job.rootId !== args.rootId) {
+    throw new HubError('HUB_CAPABILITY_DENIED', 'Job root does not match its typed arguments');
+  }
+  if (job.type === 'agent.start') {
+    if (!policy.providers?.[args.provider]?.includes(args.model)) {
+      throw new HubError('HUB_PROVIDER_MODEL_DENIED', 'Provider or model is not allowed');
+    }
+  }
+  return { ...structuredClone(job), arguments: args };
+}
+
+export function validateJobResult(type, result, { now = Date.now } = {}) {
+  const allowed = RESULT_FIELDS[type];
+  if (!allowed) throw inputError(`Unsupported job type "${type}"`);
+  if (result === null || result === undefined) return null;
+  if (typeof result !== 'object' || Array.isArray(result)) {
+    throw inputError('job result must be an object');
+  }
+  if (Buffer.byteLength(JSON.stringify(result), 'utf8') > 64 * 1024) {
+    throw inputError('job result exceeds 64 KiB');
+  }
+  for (const key of Object.keys(result)) {
+    if (!allowed.includes(key)) throw inputError(`Field "${key}" is not allowed in ${type} result`);
+  }
+  assertSafeCloudValue(result);
+  if (typeof result.summary === 'string' && result.summary.length > 8_000) {
+    throw inputError('result summary exceeds 8000 characters');
+  }
+  if (HUB_JOB_TYPES.includes(type)) {
+    if (!HUB_OUTCOMES.includes(result.outcome)) throw inputError(`hub outcome must be one of ${HUB_OUTCOMES.join(', ')}`);
+    assertString(result.summary, 'hub summary', 500);
+  }
+  if (type === 'agent.turn' && result.needsUser === true) {
+    if (!result.decision || typeof result.decision !== 'object' || Array.isArray(result.decision)) {
+      throw inputError('needsUser result requires a structured decision');
+    }
+    if (Object.keys(result.decision).some((key) => !['summary', 'options'].includes(key))) {
+      throw inputError('decision contains an unsupported field');
+    }
+    assertString(result.decision.summary, 'decision summary', 1_000);
+    if (
+      !Array.isArray(result.decision.options) ||
+      result.decision.options.length < 1 ||
+      result.decision.options.length > 10
+    ) {
+      throw inputError('decision options must contain 1 to 10 entries');
+    }
+    for (const option of result.decision.options) {
+      if (
+        !option ||
+        typeof option !== 'object' ||
+        Array.isArray(option) ||
+        Object.keys(option).some((key) => !['id', 'label', 'impact'].includes(key))
+      ) {
+        throw inputError('decision option contains an unsupported field');
+      }
+      assertString(option.id, 'decision option id', 80);
+      assertString(option.label, 'decision option label', 240);
+      assertString(option.impact, 'decision option impact', 1_000, { optional: true });
+    }
+  }
+  if (type === 'evidence.collect') {
+    if (!Array.isArray(result.artifacts) || result.artifacts.length < 1 || result.artifacts.length > 20) {
+      throw inputError('evidence artifacts must contain 1 to 20 entries');
+    }
+    const allowedArtifactFields = new Set([
+      'kind', 'label', 'mimeType', 'byteSize', 'sha256', 'storageMode',
+      'contentText', 'reference', 'expiresAt', 'redactionVersion', 'userVisible',
+    ]);
+    for (const artifact of result.artifacts) {
+      if (
+        !artifact ||
+        typeof artifact !== 'object' ||
+        Array.isArray(artifact) ||
+        Object.keys(artifact).some((key) => !allowedArtifactFields.has(key))
+      ) {
+        throw inputError('artifact contains an unsupported field');
+      }
+      if (!ARTIFACT_KINDS.has(artifact.kind)) throw inputError('artifact kind is invalid');
+      assertString(artifact.label, 'artifact label', 180);
+      assertString(artifact.mimeType, 'artifact mimeType', 100);
+      if (!Number.isInteger(artifact.byteSize) || artifact.byteSize < 0 || artifact.byteSize > 1_048_576) {
+        throw inputError('artifact byteSize is invalid');
+      }
+      if (!SHA256.test(String(artifact.sha256 || ''))) throw inputError('artifact sha256 is invalid');
+      if (!ARTIFACT_STORAGE.has(artifact.storageMode)) throw inputError('artifact storageMode is invalid');
+      if (!Number.isInteger(artifact.redactionVersion) || artifact.redactionVersion < 1) {
+        throw inputError('artifact redactionVersion is invalid');
+      }
+      if (artifact.userVisible !== true) throw inputError('artifact must be explicitly user visible');
+      if (
+        artifact.contentText !== undefined &&
+        (typeof artifact.contentText !== 'string' || artifact.contentText.length > 32_000)
+      ) {
+        throw inputError('artifact contentText is invalid');
+      }
+      if (artifact.storageMode === 'inline_redacted') {
+        if (artifact.contentText === undefined || artifact.reference !== undefined) {
+          throw inputError('inline artifact requires only redacted contentText');
+        }
+      }
+      if (artifact.storageMode === 'signed_reference') {
+        if (
+          artifact.contentText !== undefined ||
+          !artifact.reference ||
+          typeof artifact.reference !== 'object' ||
+          Array.isArray(artifact.reference) ||
+          Object.keys(artifact.reference).some(
+            (key) => !['referenceId', 'expiresAt'].includes(key)
+          )
+        ) {
+          throw inputError('signed-reference artifact requires only a structured reference');
+        }
+        assertString(artifact.reference.referenceId, 'artifact referenceId', 128);
+        assertString(artifact.reference.expiresAt, 'artifact reference expiresAt', 40);
+        assertString(artifact.expiresAt, 'artifact expiresAt', 40);
+        const referenceExpiry = Date.parse(artifact.reference.expiresAt);
+        const artifactExpiry = Date.parse(artifact.expiresAt);
+        const currentTime = now();
+        if (
+          !Number.isFinite(referenceExpiry) ||
+          !Number.isFinite(artifactExpiry) ||
+          referenceExpiry !== artifactExpiry ||
+          referenceExpiry <= currentTime ||
+          referenceExpiry > currentTime + 15 * 60 * 1_000
+        ) {
+          throw inputError('signed artifact expiry must match and be within 15 minutes');
+        }
+      }
+      if (
+        artifact.storageMode === 'local_only' &&
+        (artifact.contentText !== undefined || artifact.reference !== undefined)
+      ) {
+        throw inputError('local-only artifact cannot upload content or a reference');
+      }
+    }
+  }
+  return structuredClone(result);
+}
+
+export class IntentRegistry {
+  constructor({ handlers, policy }) {
+    this.handlers = new Map();
+    this.policy = structuredClone(policy);
+    for (const [type, handler] of Object.entries(handlers)) {
+      if (!JOB_TYPES.includes(type) || typeof handler !== 'function') {
+        throw new HubError('HUB_INTENT_HANDLER_DENIED', `Invalid job handler: ${type}`);
+      }
+      this.handlers.set(type, handler);
+    }
+  }
+
+  async execute(job, context = {}) {
+    const validated = validateIntent(job, this.policy, context);
+    const handler = this.handlers.get(validated.type);
+    if (!handler) {
+      throw new HubError('HUB_INTENT_HANDLER_MISSING', `No local handler is registered for ${validated.type}`);
+    }
+    return handler(validated, context);
+  }
+}