@awak-app/simy-cli 0.2.3 → 0.3.3

package/src/execution-capability-contract.js

@@ -0,0 +1,116 @@
+import { localTaskFileCapabilityMetadata } from "./local-task-file-capabilities.js";
+
+export const EXECUTION_CAPABILITY_SCHEMA_VERSION = "execution_capability.v1";
+export const EXECUTION_CAPABILITY_CONTRACT_VERSION = 1;
+
+export function buildExecutionCapabilityContract({
+  backends = {},
+  backendVersions = {},
+  authenticated = false,
+} = {}) {
+  const artifactTypes = supportedArtifactTypes();
+  return Object.freeze(
+    ["codex", "claude"].map((provider) =>
+      Object.freeze(
+        localExecutionCapability({
+          provider,
+          inspection: backendVersions?.[provider],
+          legacyAvailable: backends?.[provider] === true,
+          authenticated,
+          artifactTypes,
+        }),
+      ),
+    ),
+  );
+}
+
+function localExecutionCapability({
+  provider,
+  inspection,
+  legacyAvailable,
+  authenticated,
+  artifactTypes,
+}) {
+  const binary = normalizeInspection(provider, inspection, legacyAvailable);
+  const ready = authenticated && binary.compatible;
+  return {
+    schema_version: EXECUTION_CAPABILITY_SCHEMA_VERSION,
+    capability_contract_version: EXECUTION_CAPABILITY_CONTRACT_VERSION,
+    execution_target: "local",
+    provider,
+    // The CLI does not inspect Provider-managed skills, MCP configuration, or
+    // connectors. Unknown is materially different from unavailable.
+    skills: { status: "unknown", identifiers: [] },
+    mcp_servers: [],
+    connectors: [],
+    cli_binaries: [binary.public],
+    browser_capability: { status: "unknown", modes: [] },
+    supported_input_artifact_types: [...artifactTypes],
+    supported_output_artifact_types: [...artifactTypes],
+    side_effect_classes: {
+      read: { supported: true, approval_required: false },
+      write: { supported: true, approval_required: true },
+      external_side_effect: { supported: false, approval_required: true },
+    },
+    authentication_readiness: {
+      device_session: authenticated ? "ready" : "required",
+      // A version probe proves only that the binary is runnable. It does not
+      // prove the Provider account is authenticated.
+      provider: "unknown",
+    },
+    readiness: {
+      ready,
+      reason: ready
+        ? "ready"
+        : !authenticated
+          ? "device_session_required"
+          : binary.status === "outdated" || binary.status === "unknown_version"
+            ? "provider_update_required"
+            : "provider_missing",
+    },
+    missing_capability_recovery_actions: ready
+      ? []
+      : [
+          {
+            action: binary.status === "missing" ? "install_provider" : "update_provider",
+            command: binary.update_command,
+          },
+        ],
+  };
+}
+
+function normalizeInspection(provider, value, legacyAvailable = false) {
+  const inspection = value && typeof value === "object" ? value : {};
+  const compatible = inspection.compatible === true || legacyAvailable;
+  const status = cleanString(inspection.status) || (compatible ? "compatible" : "missing");
+  const publicBinary = {
+    id: provider,
+    status,
+    available: inspection.available === true || legacyAvailable,
+    compatible,
+    installed_version: cleanString(inspection.installed_version),
+    minimum_version: cleanString(inspection.minimum_version),
+    update_command: cleanString(inspection.update_command),
+  };
+  return {
+    ...publicBinary,
+    public: publicBinary,
+  };
+}
+
+function supportedArtifactTypes() {
+  const registry = localTaskFileCapabilityMetadata();
+  return Object.freeze(
+    [
+      ...new Set(
+        registry.categories.flatMap((category) =>
+          category.formats.map((format) => format.canonical_mime),
+        ),
+      ),
+    ].sort(),
+  );
+}
+
+function cleanString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/src/execution-guardrail.js

@@ -1,13 +1,21 @@
-export const EXECUTION_GUARDRAIL_POLICY_VERSION = "2026-07-21.1";
+export const EXECUTION_GUARDRAIL_POLICY_VERSION = "2026-07-26.1";
 
 const OBSERVE_PATTERN =
   /\b(monitor|watch|observe|track|status|progress|keep an eye on)\b|監視|見守|進捗|状況を?(?:見|確認)|监控|監控|观察|觀察|进度|進度|状态|狀態/i;
 const READ_PATTERN =
   /\b(explain|summari[sz]e|inspect|review|look at|read|check|diagnose|investigate)\b|説明|要約|確認|調査|レビュー|查看|解释|說明|总结|總結|检查|檢查|调查|調查|诊断|診斷/i;
+const INQUIRY_PATTERN =
+  /\b(?:can|could|would|what|which|how|whether|tell me|is it possible)\b|できますか|可能ですか|教えて|どうすれば|何が|どのように|可以吗|可以嗎|能否|怎么|怎麼|如何|什么|什麼|[?？]/i;
 const CHANGE_PATTERN =
-  /\b(implement|fix|build|create|change|update|refactor|add|remove|rename|ship|write|edit|merge|release|publish)\b|実装|修正|改善|変更|追加|削除|作成|開発|マージ|公開|发布|發佈|实现|實現|修复|修復|修改|改掉|改一下|新增|删除|刪除|重构|重構|合并|合併/i;
+  /\b(implement|fix|build|create|change|update|refactor|add|remove|delete|rename|ship|write|edit|merge|release|publish)\b|実装|修正|改善|変更|追加|削除|作成|生成|開発|マージ|公開|发布|發佈|实现|實現|修复|修復|修改|改掉|改一下|新增|删除|刪除|重构|重構|合并|合併|制作|製作|生成/i;
 const OBJECT_PATTERN =
   /\b(code|file|readme|api|ui|ux|feature|bug|pr|pull request|repository|repo|branch|test|migration|endpoint|component|page|cli|backend|extension)\b|コード|ファイル|機能|不具合|画面|ページ|テスト|移行|组件|組件|页面|頁面|代码|代碼|文件|功能|错误|錯誤|仓库|倉庫|分支/i;
+const CODING_TARGET_PATTERN =
+  /\b(code|readme|api|ui|ux|feature|bug|pr|pull request|repository|repo|branch|test|migration|endpoint|component|page|cli|backend|extension)\b|コード|機能|不具合|画面|ページ|テスト|移行|组件|組件|页面|頁面|代码|代碼|功能|错误|錯誤|仓库|倉庫|分支/i;
+const KNOWLEDGE_WORK_PATTERN =
+  /\b(report|summary|memo|brief|document|presentation|slides?|powerpoint|pptx|spreadsheet|excel|xlsx|csv|analysis|research|plan|proposal|transcript|notes?|table|chart|image|illustration|poster|banner|thumbnail|png|jpe?g)\b|レポート|要約|資料|文書|プレゼン|スライド|表計算|分析|調査|計画|提案|文字起こし|画像|イラスト|ポスター|バナー|サムネイル|报告|報告|总结|總結|文档|文檔|演示|簡報|幻灯片|試算表|表格|分析|调研|調研|计划|計劃|提案|转录|轉錄|图片|圖片|插图|插圖|海报|海報|横幅|橫幅|缩略图|縮略圖/i;
+const EXTERNAL_EFFECT_PATTERN =
+  /\b(send|post|submit|upload|purchase|pay|book|register)\b[\s\S]*\b(email|mail|slack|message|form|youtube|social|payment|order|reservation|accounting)\b|メール送信|Slack.*投稿|フォーム.*送信|アップロード|購入|支払|予約|会計.*登録|发送.*(?:邮件|Slack|消息)|發送.*(?:郵件|Slack|訊息)|发布.*消息|發佈.*訊息|提交.*表单|提交.*表單|上传|上傳|购买|購買|支付|预订|預訂|登记.*会计|登記.*會計/i;
 const VAGUE_PATTERN = /^(?:fix|do|handle|continue|change)?\s*(?:it|this|that)?[.!。！]?$/i;
 const VAGUE_CJK_PATTERN = /^(?:これ|それ|あれ|やって|直して|続けて|这个|這個|那个|那個|处理|處理|修一下)[。！]?$/i;
 const UNSUPPORTED_PATTERN =
@@ -15,7 +23,7 @@ const UNSUPPORTED_PATTERN =
 
 const MANAGED_SIGNAL_PATTERNS = [
   ["pr_merge_release", /\b(?:pull request|pr|merge|release|publish|deploy)\b|PR|マージ|リリース|デプロイ|合并|合併|发布|發佈|部署/i],
-  ["verification", /\b(?:test|e2e|integration test|until green|ci)\b|テスト|検証|通过测试|通過測試|直到.*通过|直到.*通過/i],
+  ["verification", /\b(?:tests?|e2e|integration tests?|until green|ci)\b|テスト|検証|通过测试|通過測試|直到.*通过|直到.*通過/i],
   ["browser_evidence", /\b(?:browser|screenshots?|visual evidence|evidence)\b|ブラウザ|スクリーンショット|証跡|截图|截圖|浏览器|瀏覽器|证据|證據/i],
   ["cross_repository", /\b(?:cross[- ]repo|multiple repos|multi[- ]repo)\b|複数(?:の)?リポジトリ|跨仓库|跨倉庫|多个仓库|多個倉庫/i],
   ["high_risk_change", /\b(?:migration|authentication|authorization|security|rollback)\b|移行|認証|認可|セキュリティ|ロールバック|迁移|遷移|认证|認證|授权|授權|安全|回滚|回滾/i],
@@ -42,39 +50,75 @@ export function classifyExecutionRequirement(sourceMessage) {
       reason_code: "prohibited_operation",
     });
   }
-  const changeRequested = CHANGE_PATTERN.test(source);
-  const observeRequested = OBSERVE_PATTERN.test(source);
-  const readRequested = READ_PATTERN.test(source);
-  const hasObject = OBJECT_PATTERN.test(source) || source.length >= 24;
-  const agenticSignals = MANAGED_SIGNAL_PATTERNS.filter(([, pattern]) => pattern.test(source)).map(
+  const intent = classificationIntent(source);
+  const changeRequested = CHANGE_PATTERN.test(intent);
+  const observeRequested = OBSERVE_PATTERN.test(intent);
+  const readRequested =
+    READ_PATTERN.test(intent) || (INQUIRY_PATTERN.test(intent) && !changeRequested);
+  const codingTarget = CODING_TARGET_PATTERN.test(intent);
+  const knowledgeWork = KNOWLEDGE_WORK_PATTERN.test(source);
+  const externalEffect = EXTERNAL_EFFECT_PATTERN.test(intent);
+  const hasObject = OBJECT_PATTERN.test(intent) || source.length >= 24;
+  const agenticSignals = MANAGED_SIGNAL_PATTERNS.filter(([, pattern]) => pattern.test(intent)).map(
     ([signal]) => signal,
   );
-  if (changeRequested && hasObject && agenticSignals.length >= 2) {
+  if (externalEffect && !codingTarget) {
+    return guardrail("unsupported", {
+      change_requested: true,
+      operation: "execute",
+      permission_mode: "workspace_write",
+      domain: "external_operation",
+      external_effects: "requested",
+      reason_code: "external_effect_not_supported",
+    });
+  }
+  if (changeRequested && codingTarget && hasObject && agenticSignals.length >= 2) {
     return guardrail("agentic_loop", {
       change_requested: true,
       managed_lifecycle_required: true,
       repository_required: true,
       operation: "execute",
       permission_mode: "workspace_write",
+      domain: "coding",
+      workspace_kind: "repository",
       agentic_signals: agenticSignals,
       reason_code: "managed_change_lifecycle_required",
     });
   }
   if (observeRequested && !changeRequested) {
     return guardrail("direct_executor", {
-      repository_required: /\b(?:repo|repository|pr|branch)\b|リポジトリ|仓库|倉庫|分支/i.test(source),
+      repository_required:
+        /\b(?:repo|repository|pr|branch)\b|リポジトリ|仓库|倉庫|分支/i.test(source) ||
+        codingTarget,
       operation: "observe",
       permission_mode: "read_only",
+      domain: codingTarget ? "coding" : "knowledge_work",
+      workspace_kind: codingTarget ? "repository" : "task_sandbox",
       direct_signals: ["bounded_observation", "no_persistent_change"],
       reason_code: "observe_existing_provider_session",
     });
   }
-  if (changeRequested && hasObject) {
+  if (changeRequested && knowledgeWork && !codingTarget) {
+    return guardrail("direct_executor", {
+      change_requested: true,
+      repository_required: false,
+      operation: "execute",
+      permission_mode: "workspace_write",
+      domain: "knowledge_work",
+      workspace_kind: "task_sandbox",
+      agentic_signals: [],
+      direct_signals: ["bounded_knowledge_work", "managed_lifecycle_not_required"],
+      reason_code: "bounded_knowledge_work",
+    });
+  }
+  if (changeRequested && codingTarget && hasObject) {
     return guardrail("direct_executor", {
       change_requested: true,
       repository_required: true,
       operation: "execute",
       permission_mode: "workspace_write",
+      domain: "coding",
+      workspace_kind: "repository",
       agentic_signals: agenticSignals,
       direct_signals: ["single_bounded_change", "managed_lifecycle_not_required"],
       reason_code: "bounded_change_direct_execution",
@@ -90,9 +134,11 @@ export function classifyExecutionRequirement(sourceMessage) {
   }
   if (readRequested || source.length >= 8) {
     return guardrail("direct_executor", {
-      repository_required: /\b(?:repo|repository|pr|file|code)\b|コード|ファイル|仓库|倉庫|文件|代码|代碼/i.test(source),
+      repository_required: codingTarget,
       operation: "read",
       permission_mode: "read_only",
+      domain: codingTarget ? "coding" : "knowledge_work",
+      workspace_kind: codingTarget ? "repository" : "task_sandbox",
       direct_signals: ["single_read_task", "no_managed_lifecycle"],
       reason_code: "bounded_read_direct_execution",
     });
@@ -100,6 +146,9 @@ export function classifyExecutionRequirement(sourceMessage) {
   return guardrail("needs_clarification", {
     operation: "read",
     permission_mode: "read_only",
+    domain: "knowledge_work",
+    workspace_kind: "task_sandbox",
+    external_effects: "deny",
     reason_code: "action_missing",
   });
 }
@@ -118,3 +167,11 @@ function guardrail(decision, overrides) {
     ...overrides,
   };
 }
+
+function classificationIntent(source) {
+  const leadingQuestion = source.match(/^([\s\S]{1,280}?[?？])/);
+  if (leadingQuestion && INQUIRY_PATTERN.test(leadingQuestion[1])) {
+    return leadingQuestion[1].trim();
+  }
+  return source;
+}

package/src/index.js

@@ -12,6 +12,10 @@ import {
   writeUpdateHandoffFromEnvironment,
 } from "./auto-update.js";
 import { openAuthorizationUrl } from "./browser.js";
+import {
+  createAgentShutdown,
+  installAgentShutdownSignalHandlers,
+} from "./shutdown.js";
 import { DEFAULT_WEB_ORIGIN, resolveWebOrigin } from "./web-origin.js";
 
 const argv = process.argv.slice(2);
@@ -73,6 +77,8 @@ const agent = await startAgent({
   quiet: interactive,
   updateManager,
 });
+const shutdownAgent = createAgentShutdown(agent);
+installAgentShutdownSignalHandlers({ shutdown: shutdownAgent });
 await writeUpdateHandoffFromEnvironment({ version: packageInfo.version, port: agent.port });
 updateManager.start({
   registry: agent.registry,
@@ -82,7 +88,7 @@ updateManager.start({
       argv: process.argv.slice(2),
       targetVersion,
     });
-    await closeServer(agent.server);
+    await shutdownAgent();
   },
 });
 if (agent.loginUrl && !args.has("--no-open")) {
@@ -93,7 +99,7 @@ if (interactive) {
   try {
     await runAgenticLoopConsole(agent);
   } finally {
-    await closeServer(agent.server);
+    await shutdownAgent();
   }
 }
 
@@ -117,8 +123,3 @@ function readOption(argv, name) {
   }
   return value;
 }
-
-function closeServer(server) {
-  if (!server.listening) return Promise.resolve();
-  return new Promise((resolve) => server.close(resolve));
-}

package/src/local-attachments.js

@@ -3,27 +3,26 @@ import { mkdir, open, readFile, readdir, realpath, rm, stat } from "node:fs/prom
 import os from "node:os";
 import path from "node:path";
 
-export const MAX_ATTACHMENT_COUNT = 5;
-export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
-export const MAX_ATTACHMENTS_TOTAL_BYTES = 50 * 1024 * 1024;
+import {
+  canonicalMimeTypeForFilename,
+  LOCAL_TASK_FILE_CAPABILITY_REGISTRY,
+  LocalTaskFileCapabilityError,
+  normalizeLocalTaskMimeType,
+  validateLocalTaskFile,
+  validateLocalTaskFileCollection,
+} from "./local-task-file-capabilities.js";
+
+export const MAX_ATTACHMENT_COUNT =
+  LOCAL_TASK_FILE_CAPABILITY_REGISTRY.input.max_files;
+export const MAX_ATTACHMENT_BYTES = Math.max(
+  ...LOCAL_TASK_FILE_CAPABILITY_REGISTRY.categories.map(
+    (category) => category.input_max_bytes,
+  ),
+);
+export const MAX_ATTACHMENTS_TOTAL_BYTES =
+  LOCAL_TASK_FILE_CAPABILITY_REGISTRY.input.max_total_bytes;
 const RUN_RETENTION_MS = 24 * 60 * 60 * 1000;
-const SAFE_RUN_ID = /^(?:agentic_loop|coding_loop)_[A-Za-z0-9_-]+$/;
-const ALLOWED_EXACT_MIME_TYPES = new Set([
-  "application/json",
-  "application/octet-stream",
-  "application/pdf",
-  "application/rtf",
-  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-  "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-  "application/zip",
-  "application/x-yaml",
-  "image/gif",
-  "image/jpeg",
-  "image/png",
-  "image/svg+xml",
-  "image/webp",
-]);
+const SAFE_RUN_ID = /^(?:agentic_loop|coding_loop|local_task)_[A-Za-z0-9_-]+$/;
 
 export function runsRoot(override) {
   return path.resolve(
@@ -32,56 +31,75 @@ export function runsRoot(override) {
 }
 
 export async function stageRunAttachments({ runId, attachments, manifest, root }) {
-  if (!SAFE_RUN_ID.test(runId)) throw new Error("invalid agentic loop run_id");
+  const prepared = await prepareRunAttachments({ attachments, manifest });
+  return stagePreparedRunAttachments({ runId, prepared, root });
+}
+
+export async function prepareRunAttachments({ attachments, manifest }) {
   if (!Array.isArray(attachments) || attachments.length === 0) return [];
-  if (attachments.length > MAX_ATTACHMENT_COUNT) {
-    throw new Error(`at most ${MAX_ATTACHMENT_COUNT} attachments are allowed`);
-  }
   if (manifest !== undefined && (!Array.isArray(manifest) || manifest.length !== attachments.length)) {
-    throw new Error("attachment manifest does not match uploaded files");
+    throw new LocalTaskFileCapabilityError(
+      "The attachment list no longer matches the files you selected.",
+      {
+        code: "local_task_attachment_manifest_mismatch",
+        recoveryAction:
+          LOCAL_TASK_FILE_CAPABILITY_REGISTRY.recovery_actions.reattach_file,
+      },
+    );
+  }
+  const prepared = [];
+  for (const [index, attachment] of attachments.entries()) {
+    const name = String(attachment.name || "");
+    const mimeType = String(attachment.type || "").trim()
+      ? normalizeLocalTaskMimeType(attachment.type)
+      : canonicalMimeTypeForFilename(name);
+    const bytes = Buffer.from(await attachment.arrayBuffer());
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    if (manifest) verifyManifestEntry(manifest[index], { name, mimeType, size: bytes.length, sha256 });
+    const validated = validateLocalTaskFile({
+      name,
+      mime_type: mimeType,
+      size_bytes: bytes.length,
+      sha256,
+      bytes,
+    });
+    prepared.push({ ...validated, bytes });
   }
+  validateLocalTaskFileCollection(prepared, {
+    direction: "input",
+    requireBytes: true,
+  });
+  return prepared;
+}
+
+export async function stagePreparedRunAttachments({ runId, prepared, root }) {
+  if (!SAFE_RUN_ID.test(runId)) throw new Error("invalid local execution run_id");
+  if (!Array.isArray(prepared) || prepared.length === 0) return [];
 
   const runRoot = path.join(runsRoot(root), runId);
   const inputsRoot = path.join(runRoot, "inputs");
+  const localTask = runId.startsWith("local_task_");
   await mkdir(runsRoot(root), { recursive: true, mode: 0o700 });
-  await mkdir(runRoot, { mode: 0o700 });
-  await mkdir(inputsRoot, { mode: 0o700 });
+  await mkdir(runRoot, { recursive: localTask, mode: 0o700 });
+  await mkdir(inputsRoot, { recursive: localTask, mode: 0o700 });
   const staged = [];
-  let totalBytes = 0;
 
   try {
-    for (const [index, attachment] of attachments.entries()) {
-      const name = safeAttachmentName(attachment.name);
-      const mimeType = normalizeMimeType(attachment.type);
-      if (!isAllowedMimeType(mimeType)) {
-        throw new Error(`attachment ${name} has unsupported MIME type ${mimeType || "unknown"}`);
-      }
-      const bytes = Buffer.from(await attachment.arrayBuffer());
-      if (bytes.length > MAX_ATTACHMENT_BYTES) {
-        throw new Error(`attachment ${name} exceeds the 20 MB limit`);
-      }
-      totalBytes += bytes.length;
-      if (totalBytes > MAX_ATTACHMENTS_TOTAL_BYTES) {
-        throw new Error("attachments exceed the 50 MB total limit");
-      }
-
-      const sha256 = createHash("sha256").update(bytes).digest("hex");
-      if (manifest) verifyManifestEntry(manifest[index], { name, mimeType, size: bytes.length, sha256 });
-
+    for (const attachment of prepared) {
       const id = `attachment_${randomUUID()}`;
-      const localPath = path.join(inputsRoot, `${id}-${name}`);
+      const localPath = path.join(inputsRoot, `${id}-${attachment.name}`);
       const handle = await open(localPath, "wx", 0o600);
       try {
-        await handle.writeFile(bytes);
+        await handle.writeFile(attachment.bytes);
       } finally {
         await handle.close();
       }
       staged.push({
         id,
-        name,
-        mime_type: mimeType,
-        size_bytes: bytes.length,
-        sha256,
+        name: attachment.name,
+        mime_type: attachment.mime_type,
+        size_bytes: attachment.size_bytes,
+        sha256: attachment.sha256,
         local_path: localPath,
         integrity_status: "verified",
         staged_at: new Date().toISOString(),
@@ -110,29 +128,28 @@ export async function cleanupRunAttachments(attachments) {
 
 export async function referenceLocalAttachmentPaths(values) {
   const paths = [...new Set((values || []).map((value) => path.resolve(String(value))))];
-  if (paths.length > MAX_ATTACHMENT_COUNT) {
-    throw new Error(`at most ${MAX_ATTACHMENT_COUNT} attachments are allowed`);
-  }
-  let totalBytes = 0;
   const attachments = [];
   for (const value of paths) {
     const resolved = await realpath(value);
     const details = await stat(resolved);
-    if (!details.isFile()) throw new Error(`${value} is not a file`);
-    if (details.size > MAX_ATTACHMENT_BYTES) {
-      throw new Error(`${path.basename(resolved)} exceeds the 20 MB limit`);
-    }
-    totalBytes += details.size;
-    if (totalBytes > MAX_ATTACHMENTS_TOTAL_BYTES) {
-      throw new Error("attachments exceed the 50 MB total limit");
+    if (!details.isFile()) {
+      throw new LocalTaskFileCapabilityError(`${value} is not a file`, {
+        code: "local_task_file_not_found",
+        recoveryAction:
+          LOCAL_TASK_FILE_CAPABILITY_REGISTRY.recovery_actions.reattach_file,
+      });
     }
     const bytes = await readFile(resolved);
-    attachments.push({
-      id: `attachment_${randomUUID()}`,
-      name: safeAttachmentName(path.basename(resolved)),
-      mime_type: inferMimeType(resolved),
+    const validated = validateLocalTaskFile({
+      name: path.basename(resolved),
+      mime_type: canonicalMimeTypeForFilename(resolved),
       size_bytes: details.size,
       sha256: createHash("sha256").update(bytes).digest("hex"),
+      bytes,
+    }, { requireBytes: true });
+    attachments.push({
+      id: `attachment_${randomUUID()}`,
+      ...validated,
       local_path: resolved,
       integrity_status: "verified",
       staged_at: new Date().toISOString(),
@@ -144,6 +161,7 @@ export async function referenceLocalAttachmentPaths(values) {
       storage: "source_path",
     });
   }
+  validateLocalTaskFileCollection(attachments, { direction: "input" });
   return attachments;
 }
 
@@ -212,59 +230,22 @@ export function markAttachmentsCleanupFailed(attachments, error) {
   }
 }
 
-function safeAttachmentName(value) {
-  const name = String(value || "")
-    .normalize("NFKC")
-    .replace(/[\u0000-\u001f\u007f]/g, "")
-    .trim();
-  if (!name || name !== path.basename(name) || name === "." || name === "..") {
-    throw new Error("attachment has an invalid file name");
-  }
-  if (name.length > 180) throw new Error("attachment file name exceeds 180 characters");
-  return name;
-}
-
-function normalizeMimeType(value) {
-  return String(value || "application/octet-stream")
-    .split(";", 1)[0]
-    .trim()
-    .toLowerCase();
-}
-
-function isAllowedMimeType(value) {
-  return value.startsWith("text/") || ALLOWED_EXACT_MIME_TYPES.has(value);
-}
-
-function inferMimeType(value) {
-  const extension = path.extname(value).toLowerCase();
-  return (
-    {
-      ".gif": "image/gif",
-      ".jpeg": "image/jpeg",
-      ".jpg": "image/jpeg",
-      ".json": "application/json",
-      ".md": "text/markdown",
-      ".pdf": "application/pdf",
-      ".png": "image/png",
-      ".svg": "image/svg+xml",
-      ".txt": "text/plain",
-      ".webp": "image/webp",
-      ".yaml": "application/x-yaml",
-      ".yml": "application/x-yaml",
-      ".zip": "application/zip",
-    }[extension] || "application/octet-stream"
-  );
-}
-
 function verifyManifestEntry(value, actual) {
   if (
     !value ||
     typeof value !== "object" ||
     value.name !== actual.name ||
-    normalizeMimeType(value.mime_type) !== actual.mimeType ||
+    normalizeLocalTaskMimeType(value.mime_type) !== actual.mimeType ||
     value.size_bytes !== actual.size ||
     String(value.sha256 || "").toLowerCase() !== actual.sha256
   ) {
-    throw new Error(`attachment integrity check failed for ${actual.name}`);
+    throw new LocalTaskFileCapabilityError(
+      `The attachment integrity check failed for ${actual.name}.`,
+      {
+        code: "local_task_attachment_manifest_mismatch",
+        recoveryAction:
+          LOCAL_TASK_FILE_CAPABILITY_REGISTRY.recovery_actions.reattach_file,
+      },
+    );
   }
 }