@thinkingai/ae-cli 6.0.52 → 6.0.54

package/dist/things-VPPXXLHB.js

@@ -0,0 +1,1091 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
+import {
+  resolveMemoryApiBaseUrl
+} from "./chunk-D6ACFILC.js";
+import "./chunk-4655PUNX.js";
+import "./chunk-PLE722AJ.js";
+import {
+  CapabilityGatewayError,
+  buildCapabilityGatewayUrl,
+  callCapabilityApi
+} from "./chunk-EOYSKMXN.js";
+import "./chunk-Y74WTIKJ.js";
+import "./chunk-GIK6EDUG.js";
+import "./chunk-UQ77JXYH.js";
+import {
+  PermissionError
+} from "./chunk-WNGFSIOB.js";
+
+// src/commands/things/parity-actions.ts
+import { readFileSync } from "fs";
+var stringFlag = (name, desc, required = false) => ({
+  name,
+  type: "string",
+  desc,
+  required
+});
+var conversationFlag = stringFlag(
+  "conversation-id",
+  "Owned conversation ID",
+  true
+);
+var contentFlags = [
+  { ...stringFlag("content", "Text content"), sensitive: true },
+  { ...stringFlag("file", "UTF-8 text file"), sensitive: true },
+  { name: "stdin", type: "boolean", desc: "Read text from stdin" }
+];
+function content(ctx) {
+  if ([
+    Boolean(ctx.str("content")),
+    Boolean(ctx.str("file")),
+    ctx.bool("stdin")
+  ].filter(Boolean).length !== 1)
+    throw new Error("Specify exactly one of --content, --file or --stdin");
+  if (ctx.bool("stdin") && process.stdin.isTTY)
+    throw new Error("Pipe text to --stdin");
+  return ctx.str("content") || readFileSync(ctx.str("file") || 0, "utf8");
+}
+function parityActions(id, pageFlags2, pageQuery2) {
+  const thingFlag = stringFlag("id", "Thing ID", true);
+  const conversationPath = (ctx) => `/things/conversation/${id(ctx.str("conversationId"))}`;
+  return [
+    ...["members", "options"].map((command) => ({
+      command,
+      method: "GET",
+      suffix: () => `/things/${command}`,
+      flags: [
+        ...pageFlags2,
+        ...command === "options" ? [stringFlag("query", "Search candidates")] : []
+      ],
+      params: (ctx) => ({
+        ...pageQuery2(ctx),
+        ...command === "options" && ctx.str("query") ? { query: ctx.str("query") } : {}
+      })
+    })),
+    ...["add", "remove"].map((command) => ({
+      resource: "collaborator",
+      command,
+      method: command === "remove" ? "DELETE" : "POST",
+      suffix: (ctx) => `/things/${id(ctx.str("id"))}/collaborators`,
+      flags: [thingFlag, stringFlag("user-id", "Space member ID", true)],
+      body: (ctx) => ({ userId: id(ctx.str("userId")) })
+    })),
+    {
+      resource: "entry",
+      command: "update",
+      method: "PATCH",
+      suffix: (ctx) => `/things/${id(ctx.str("id"))}/entries/${id(ctx.str("entryId"))}`,
+      flags: [
+        thingFlag,
+        stringFlag("entry-id", "Entry ID", true),
+        stringFlag(
+          "expected-updated-at",
+          "Timestamp from the latest entry read",
+          true
+        ),
+        ...contentFlags,
+        { ...stringFlag("title", "Entry title"), sensitive: true },
+        { name: "clear-title", type: "boolean", desc: "Clear the entry title" },
+        stringFlag("type", "note | url | progress")
+      ],
+      validate: (ctx) => {
+        if (ctx.str("title") && ctx.bool("clearTitle"))
+          throw new Error("Use --title or --clear-title");
+        if (ctx.str("type") && !["note", "url", "progress"].includes(ctx.str("type")))
+          throw new Error("Entry type must be note, url or progress");
+        if (ctx.str("title") && !ctx.str("title").trim())
+          throw new Error("Entry title must not be blank");
+        if (ctx.str("title").trim().length > 200)
+          throw new Error("Entry title exceeds 200 characters");
+        if (!["content", "file", "title", "type"].some((key) => ctx.str(key)) && !ctx.bool("stdin") && !ctx.bool("clearTitle"))
+          throw new Error("Provide at least one entry field to update");
+      },
+      body: (ctx) => ({
+        ...ctx.str("content") || ctx.str("file") || ctx.bool("stdin") ? { content: content(ctx) } : {},
+        ...ctx.bool("clearTitle") ? { title: null } : ctx.str("title") ? { title: ctx.str("title") } : {},
+        ...ctx.str("type") ? { type: ctx.str("type") } : {},
+        expectedUpdatedAt: ctx.str("expectedUpdatedAt")
+      })
+    },
+    {
+      resource: "conversation",
+      command: "get",
+      method: "GET",
+      suffix: (ctx) => `${conversationPath(ctx)}/snapshot`,
+      flags: [conversationFlag]
+    },
+    {
+      resource: "conversation",
+      command: "primary",
+      method: "GET",
+      suffix: conversationPath,
+      flags: [conversationFlag]
+    },
+    ...["bind", "unbind"].map((command) => ({
+      resource: "conversation",
+      command,
+      method: "POST",
+      suffix: conversationPath,
+      risk: command === "unbind" ? "high-risk-write" : "write",
+      flags: [conversationFlag, ...command === "bind" ? [thingFlag] : []],
+      body: (ctx) => ({
+        primaryThingId: command === "bind" ? id(ctx.str("id")) : null
+      })
+    })),
+    {
+      command: "from-message",
+      method: "POST",
+      suffix: () => "/things/from-message",
+      flags: [
+        conversationFlag,
+        stringFlag("message-id", "Source message ID", true),
+        ...contentFlags,
+        stringFlag("id", "Existing thing ID; omit to create from --title"),
+        { ...stringFlag("title", "New thing title"), sensitive: true },
+        stringFlag(
+          "entry-type",
+          "note | progress; only with --id (default: note)"
+        )
+      ],
+      validate: (ctx) => {
+        if (Boolean(ctx.str("id")) === Boolean(ctx.str("title")))
+          throw new Error("Specify either --id or --title");
+        if (ctx.str("title") && ctx.str("entryType"))
+          throw new Error(
+            "--entry-type is only supported with --id, not --title"
+          );
+      },
+      body: (ctx) => {
+        return {
+          conversationId: id(ctx.str("conversationId")),
+          messageId: id(ctx.str("messageId")),
+          content: content(ctx),
+          ...ctx.str("entryType") ? { entryType: ctx.str("entryType") } : {},
+          ...ctx.str("id") ? { thingId: id(ctx.str("id")) } : { fields: { title: ctx.str("title") } }
+        };
+      }
+    }
+  ];
+}
+
+// src/commands/things/client.ts
+function thingsUrl(ctx, path) {
+  return buildCapabilityGatewayUrl(
+    resolveMemoryApiBaseUrl(ctx.host()),
+    "things",
+    path,
+    {},
+    "v1"
+  );
+}
+async function requestThings(ctx, method, path, body) {
+  try {
+    return await callCapabilityApi(ctx.host(), "things", path, method, body, {
+      apiBaseUrl: resolveMemoryApiBaseUrl(ctx.host()),
+      apiVersion: "v1",
+      includeClientContextInBody: false,
+      retryOnInvalidTokenForbidden: false
+    });
+  } catch (error) {
+    if (error instanceof PermissionError)
+      throw new PermissionError(
+        "You cannot access this workspace thing.",
+        error.code
+      );
+    if (error instanceof CapabilityGatewayError) {
+      const messages = {
+        THING_VERSION_CONFLICT: "The thing changed. Read it again and submit the current expected version.",
+        THING_TARGET_CONFLICT: "The requested target conflicts with the conversation or execution.",
+        THING_CONTEXT_UNAVAILABLE: "The execution snapshot is missing or invalid. Start a new execution; do not fall back to live context.",
+        THING_ASSET_UNAVAILABLE: "A referenced file is missing or cannot be verified. Restore it or update the thing references.",
+        THING_TARGET_REQUIRED: "Specify --agent-space-id or run inside a Web Agent conversation.",
+        THING_NOT_FOUND: "The thing does not exist or is not accessible in this space.",
+        THING_READ_ONLY: "The requested resource is read-only and cannot be modified.",
+        THING_COMMAND_CONFLICT: "The command ID was already used with different input.",
+        THING_INVALID_INPUT: "Invalid thing input. Check identifiers, fields and limits."
+      };
+      throw new CapabilityGatewayError(
+        messages[error.code ?? ""] ?? "Workspace thing request failed. Inspect the error code.",
+        error.code,
+        error.httpStatus
+      );
+    }
+    throw error;
+  }
+}
+
+// src/commands/things/collect.ts
+async function collectThingsPages(fetchPage, maximum = 1e4) {
+  const items = [];
+  const ids = /* @__PURE__ */ new Set();
+  const cursors = /* @__PURE__ */ new Set();
+  let cursor;
+  for (let pageIndex = 0; pageIndex < 100; pageIndex++) {
+    let page;
+    try {
+      page = await fetchPage(cursor);
+    } catch {
+      return {
+        items,
+        fetchedCount: items.length,
+        truncated: true,
+        collectionError: "PAGE_REQUEST_FAILED"
+      };
+    }
+    if (!page || !Array.isArray(page.items) || !(page.nextCursor === null || typeof page.nextCursor === "string"))
+      return {
+        items,
+        fetchedCount: items.length,
+        truncated: true,
+        collectionError: "INVALID_PAGE"
+      };
+    for (const item of page.items) {
+      if (!item || typeof item.id !== "string" || ids.has(item.id))
+        return {
+          items,
+          fetchedCount: items.length,
+          truncated: true,
+          collectionError: "DUPLICATE_OR_INVALID_ITEM"
+        };
+      if (items.length >= maximum)
+        return {
+          items,
+          fetchedCount: items.length,
+          truncated: true,
+          collectionError: "COLLECTION_LIMIT"
+        };
+      ids.add(item.id);
+      items.push(item);
+    }
+    if (!page.nextCursor)
+      return {
+        items,
+        fetchedCount: items.length,
+        truncated: false,
+        collectionError: null
+      };
+    if (cursors.has(page.nextCursor) || !page.items.length)
+      return {
+        items,
+        fetchedCount: items.length,
+        truncated: true,
+        collectionError: "CURSOR_DID_NOT_ADVANCE"
+      };
+    cursors.add(page.nextCursor);
+    cursor = page.nextCursor;
+  }
+  return {
+    items,
+    fetchedCount: items.length,
+    truncated: true,
+    collectionError: "COLLECTION_LIMIT"
+  };
+}
+function thingsWindow(ctx) {
+  const start = ctx.str("from");
+  const end = ctx.str("to");
+  const timeZone = ctx.str("timeZone") || "Asia/Shanghai";
+  try {
+    new Intl.DateTimeFormat("en", { timeZone });
+  } catch {
+    throw new Error("Invalid --time-zone");
+  }
+  if (Boolean(start) !== Boolean(end))
+    throw new Error("Specify both --from and --to with explicit timezones");
+  for (const value of [start, end].filter(Boolean))
+    if (!/T.*(?:Z|[+-]\d{2}:\d{2})$/.test(value) || !Number.isFinite(Date.parse(value)))
+      throw new Error("Use ISO timestamps with explicit timezone offsets");
+  if (start && Date.parse(start) >= Date.parse(end))
+    throw new Error("--from must be earlier than --to");
+  return {
+    start: start ? new Date(start).toISOString() : null,
+    end: end ? new Date(end).toISOString() : null,
+    timeZone
+  };
+}
+function factsInWindow(thing, entries, start, end) {
+  const effective = (entry) => entry.type === "progress";
+  const startMs = start ? Date.parse(start) : -Infinity;
+  const endMs = end ? Date.parse(end) : Infinity;
+  const ordered = [...entries].sort(
+    (a, b) => Date.parse(String(b.createdAt)) - Date.parse(String(a.createdAt)) || (String(a.id) < String(b.id) ? 1 : String(a.id) > String(b.id) ? -1 : 0)
+  );
+  const inWindow = ordered.filter(
+    (e) => Date.parse(String(e.createdAt)) >= startMs && Date.parse(String(e.createdAt)) < endMs
+  );
+  const baseline = Object.fromEntries(
+    ["status", "assigneeId", "tags"].map((key) => [key, thing[key]])
+  );
+  baseline.archived = Boolean(thing.archivedAt);
+  for (const entry of ordered) {
+    if (Date.parse(String(entry.createdAt)) < startMs) continue;
+    if (entry.type === "updated" && entry.dataJson && typeof entry.dataJson === "object")
+      for (const [key, change] of Object.entries(entry.dataJson)) {
+        if (key in baseline && change && typeof change === "object" && "before" in change)
+          baseline[key] = change.before;
+      }
+    if (entry.type === "status" && entry.dataJson && typeof entry.dataJson === "object" && "before" in entry.dataJson) {
+      baseline.status = entry.dataJson.before;
+      baseline.archived = entry.dataJson.before === "archived";
+    }
+  }
+  return {
+    baseline: !start || Date.parse(String(thing.createdAt)) >= startMs ? null : baseline,
+    entries: inWindow,
+    effectiveProgressCount: inWindow.filter((e) => effective(e)).length,
+    lastEffectiveRecordBeforeWindow: ordered.find(
+      (e) => effective(e) && Date.parse(String(e.createdAt)) < startMs
+    ) ?? null
+  };
+}
+async function collectThingDetail(ctx, root2, id) {
+  const thing = await requestThings(ctx, "GET", `${root2}/things/${id}`);
+  const entries = await collectThingsPages(
+    (cursor) => requestThings(
+      ctx,
+      "GET",
+      `${root2}/things/${id}/entries?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`
+    )
+  );
+  const assets = await collectThingsPages(
+    (cursor) => requestThings(
+      ctx,
+      "GET",
+      `${root2}/things/${id}/assets?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`
+    )
+  );
+  const context = await requestThings(
+    ctx,
+    "GET",
+    `${root2}/things/${id}/context`
+  );
+  return {
+    thing,
+    entries: entries.items,
+    context,
+    assets: assets.items,
+    fetchedCount: 1 + entries.fetchedCount + assets.fetchedCount,
+    truncated: entries.truncated || assets.truncated,
+    collectionErrors: [entries.collectionError, assets.collectionError].filter(
+      Boolean
+    ),
+    consistency: context.thing.version === thing.version ? "non_transactional" : "changed_during_collection",
+    collectedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function collectThingDigest(ctx, root2, explicitIds2) {
+  const window = thingsWindow(ctx);
+  const params = new URLSearchParams({ limit: "100" });
+  if (ctx.str("assigneeId")) params.set("assigneeId", ctx.str("assigneeId"));
+  const listing = explicitIds2.length ? {
+    items: explicitIds2.map((id) => ({ id })),
+    truncated: false,
+    collectionError: null
+  } : await (async () => {
+    const pages = await Promise.all(
+      ["", "archived"].map(
+        (status) => collectThingsPages(
+          (cursor) => requestThings(
+            ctx,
+            "GET",
+            `${root2}/things?${params}${status ? `&status=${status}` : ""}${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`
+          )
+        )
+      )
+    );
+    return {
+      items: [
+        ...new Map(
+          pages.flatMap((page) => page.items).map((item) => [item.id, item])
+        ).values()
+      ],
+      truncated: pages.some((page) => page.truncated),
+      collectionError: pages.find((page) => page.collectionError)?.collectionError ?? null
+    };
+  })();
+  const items = [];
+  const unreadable = [];
+  for (const item of listing.items) {
+    try {
+      const detail = await collectThingDetail(ctx, root2, item.id);
+      const facts = factsInWindow(
+        detail.thing,
+        detail.entries,
+        window.start,
+        window.end
+      );
+      items.push({
+        ...detail,
+        ...facts,
+        baseline: detail.truncated || detail.consistency === "changed_during_collection" ? null : facts.baseline
+      });
+    } catch {
+      unreadable.push({ id: item.id, code: "ITEM_UNREADABLE" });
+    }
+  }
+  const statuses = ["open", "paused", "done"];
+  const counts = Object.fromEntries(
+    statuses.map((status) => [
+      status,
+      items.filter((i) => !i.thing.archivedAt && i.thing.status === status).length
+    ])
+  );
+  return {
+    items,
+    counts,
+    archivedCount: items.filter((i) => Boolean(i.thing.archivedAt)).length,
+    ...explicitIds2.length ? { requestedCount: explicitIds2.length, unreadable } : { unreadableCount: unreadable.length },
+    fetchedCount: items.length,
+    truncated: listing.truncated || unreadable.length > 0 || items.some((i) => i.truncated),
+    collectionError: listing.collectionError,
+    consistency: items.some(
+      (i) => i.consistency === "changed_during_collection"
+    ) ? "changed_during_collection" : "non_transactional",
+    collectedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    window
+  };
+}
+
+// src/commands/things/index.ts
+import { randomUUID } from "crypto";
+import { readFileSync as readFileSync2 } from "fs";
+var targetFlags = [
+  {
+    name: "agent-space-id",
+    type: "string",
+    desc: "Explicit space; must match the current conversation"
+  }
+];
+var idFlag = {
+  name: "id",
+  type: "string",
+  required: true,
+  desc: "Resource ID returned by the API"
+};
+var commandFlag = {
+  name: "command-id",
+  type: "string",
+  desc: "Stable UUID for safe retries; generated when omitted"
+};
+var versionFlag = {
+  name: "expected-version",
+  type: "number",
+  required: true,
+  min: 1,
+  desc: "Version read before this edit"
+};
+var pageFlags = [
+  {
+    name: "limit",
+    type: "number",
+    min: 1,
+    max: 100,
+    desc: "Page size, at most 100"
+  },
+  {
+    name: "cursor",
+    type: "string",
+    desc: "Opaque cursor from the previous response"
+  }
+];
+var thingFlags = [
+  {
+    name: "title",
+    type: "string",
+    sensitive: true,
+    desc: "Thing title, 1 to 200 characters"
+  },
+  {
+    name: "description",
+    type: "string",
+    sensitive: true,
+    desc: "Required when creating; at most 10000 characters"
+  },
+  {
+    name: "tags",
+    type: "string",
+    sensitive: true,
+    desc: "JSON array of tags; [] clears tags"
+  },
+  { name: "status", type: "string", desc: "open | paused | done" },
+  {
+    name: "assignee-id",
+    type: "string",
+    desc: "Active member ID; creation defaults to self; null is rejected"
+  },
+  {
+    name: "collaborator-ids",
+    type: "string",
+    desc: "JSON array of member IDs; [] clears collaborators"
+  },
+  {
+    name: "file",
+    type: "string",
+    sensitive: true,
+    desc: "UTF-8 JSON file containing thing fields"
+  },
+  {
+    name: "stdin",
+    type: "boolean",
+    desc: "Read thing field JSON from standard input"
+  }
+];
+function validThingsId(value) {
+  if (!/^[A-Za-z0-9_-]{1,191}$/.test(value))
+    throw new Error("Invalid resource identifier");
+  return value;
+}
+function thingsTarget(ctx) {
+  const agentSpaceId = ctx.str("agentSpaceId").trim();
+  const conversationId = process.env.TE_AGENT_CONVERSATION_ID?.trim();
+  if (!agentSpaceId && !conversationId)
+    throw new Error(
+      "Specify --agent-space-id or run inside a Web Agent conversation"
+    );
+  return {
+    ...agentSpaceId ? { agentSpaceId: validThingsId(agentSpaceId) } : {},
+    ...conversationId ? { conversationId: validThingsId(conversationId) } : {}
+  };
+}
+function query(values) {
+  const q = new URLSearchParams();
+  for (const [key, value] of Object.entries(values))
+    if (value !== void 0) q.set(key, String(value));
+  return q.size ? `?${q}` : "";
+}
+async function root(ctx) {
+  const selected = thingsTarget(ctx);
+  const resolved = await requestThings(
+    ctx,
+    "GET",
+    `target${query(selected)}`
+  );
+  const id = validThingsId(resolved.agentSpaceId);
+  if (selected.agentSpaceId && selected.agentSpaceId !== id)
+    throw new Error("Server resolved a conflicting space");
+  return `agent-spaces/${id}`;
+}
+function pageQuery(ctx) {
+  const limit = ctx.optionalNum("limit") ?? 50;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+    throw new Error("--limit must be between 1 and 100");
+  return { limit, ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} };
+}
+function thingBody(ctx) {
+  if (ctx.str("file") && ctx.bool("stdin"))
+    throw new Error("Use either --file or --stdin");
+  if (ctx.bool("stdin") && process.stdin.isTTY)
+    throw new Error("Pipe JSON to --stdin");
+  const input = ctx.str("file") ? readFileSync2(ctx.str("file"), "utf8") : ctx.bool("stdin") ? readFileSync2(0, "utf8") : "";
+  let fields;
+  try {
+    fields = input ? JSON.parse(input) : {};
+  } catch {
+    throw new Error("Invalid thing JSON. Supply a valid JSON object.");
+  }
+  if (!fields || Array.isArray(fields) || typeof fields !== "object")
+    throw new Error("Input must be an thing field object");
+  const allowed = [
+    "title",
+    "description",
+    "tags",
+    "status",
+    "assigneeId",
+    "collaboratorIds"
+  ];
+  if (Object.keys(fields).some((key) => !allowed.includes(key)))
+    throw new Error("Input contains unsupported thing fields");
+  for (const key of allowed) {
+    const value = ctx.str(key);
+    if (value) {
+      if (["tags", "collaboratorIds"].includes(key)) {
+        try {
+          fields[key] = JSON.parse(value);
+        } catch {
+          throw new Error(`--${key} requires a JSON string array`);
+        }
+      } else fields[key] = value;
+    }
+  }
+  if (fields.assigneeId !== void 0 && (fields.assigneeId === null || fields.assigneeId === "null" || typeof fields.assigneeId !== "string" || !fields.assigneeId.trim()))
+    throw new Error(
+      "Assignee must be an active member ID; null is not allowed"
+    );
+  for (const key of ["tags", "collaboratorIds"]) {
+    if (fields[key] !== void 0 && (!Array.isArray(fields[key]) || !fields[key].every((value) => typeof value === "string")))
+      throw new Error(`${key} must be a string array`);
+  }
+  if (fields.status && !["open", "paused", "done"].includes(String(fields.status)))
+    throw new Error("Invalid thing status");
+  return fields;
+}
+var validateAttachmentRole = (ctx) => {
+  if (ctx.str("role") && ctx.str("role") !== "attachment")
+    throw new Error("--role only accepts attachment");
+};
+var thingId = (ctx) => validThingsId(ctx.str("id"));
+function sourceBody(ctx) {
+  if (ctx.str("conversationId") && process.env.TE_AGENT_CONVERSATION_ID && ctx.str("conversationId") !== process.env.TE_AGENT_CONVERSATION_ID)
+    throw new Error(
+      "Source conversation must match the current execution conversation"
+    );
+  const conversationId = ctx.str("conversationId") || process.env.TE_AGENT_CONVERSATION_ID;
+  return {
+    ...conversationId ? { conversationId: validThingsId(conversationId) } : {},
+    ...ctx.str("runId") ? { runId: validThingsId(ctx.str("runId")) } : {}
+  };
+}
+var actions = [
+  ...parityActions(validThingsId, pageFlags, pageQuery),
+  {
+    resource: "asset",
+    command: "available",
+    method: "GET",
+    suffix: () => "/things/assets",
+    flags: [...pageFlags],
+    params: pageQuery
+  },
+  {
+    resource: "asset",
+    command: "list",
+    method: "GET",
+    suffix: (ctx) => `/things/${thingId(ctx)}/assets`,
+    flags: [idFlag, ...pageFlags],
+    params: pageQuery
+  },
+  {
+    resource: "asset",
+    command: "link",
+    validate: (ctx) => {
+      validateAttachmentRole(ctx);
+      if (Boolean(ctx.str("assetId")) === Boolean(ctx.str("path")))
+        throw new Error("Specify exactly one of --asset-id or --path");
+    },
+    method: "POST",
+    suffix: (ctx) => `/things/${thingId(ctx)}/assets`,
+    flags: [
+      idFlag,
+      {
+        name: "asset-id",
+        type: "string",
+        desc: "Stable space asset ID"
+      },
+      {
+        name: "path",
+        type: "string",
+        sensitive: true,
+        desc: "Space-relative file path returned by asset available"
+      },
+      {
+        name: "role",
+        type: "string",
+        desc: "attachment (default; only supported role)"
+      }
+    ],
+    body: (ctx) => ({
+      ...ctx.str("assetId") ? { assetId: validThingsId(ctx.str("assetId")) } : { path: ctx.str("path") },
+      role: ctx.str("role") || "attachment"
+    })
+  },
+  {
+    resource: "asset",
+    command: "unlink",
+    method: "DELETE",
+    suffix: (ctx) => `/things/${thingId(ctx)}/assets`,
+    flags: [
+      idFlag,
+      {
+        name: "asset-id",
+        type: "string",
+        required: true,
+        desc: "Stable space asset ID"
+      }
+    ],
+    body: (ctx) => ({ assetId: validThingsId(ctx.str("assetId")) })
+  },
+  {
+    resource: "asset",
+    command: "publish",
+    validate: validateAttachmentRole,
+    method: "POST",
+    suffix: (ctx) => `/things/${thingId(ctx)}/publish-asset`,
+    flags: [
+      idFlag,
+      {
+        name: "conversation-id",
+        type: "string",
+        desc: "Owned conversation containing the artifact"
+      },
+      {
+        name: "artifact-id",
+        type: "string",
+        desc: "Verified file artifact ID"
+      },
+      {
+        name: "file-token",
+        type: "string",
+        sensitive: true,
+        desc: "Verified directory child file token"
+      },
+      {
+        name: "source-path",
+        type: "string",
+        sensitive: true,
+        desc: "Absolute delivered file path in this conversation sandbox artifacts directory"
+      },
+      {
+        name: "run-id",
+        type: "string",
+        desc: "Verified execution ID, required with --source-path"
+      },
+      {
+        name: "destination-path",
+        type: "string",
+        sensitive: true,
+        desc: "Existing folder within space documents"
+      },
+      {
+        name: "role",
+        type: "string",
+        desc: "attachment (default; only supported role)"
+      },
+      {
+        name: "confirm-share",
+        type: "boolean",
+        desc: "User explicitly authorized making this artifact visible to all space members"
+      }
+    ],
+    body: (ctx) => {
+      if (!ctx.bool("confirmShare"))
+        throw new Error(
+          "Explicit sharing authorization is required: --confirm-share"
+        );
+      if ([
+        ctx.str("artifactId"),
+        ctx.str("fileToken"),
+        ctx.str("sourcePath")
+      ].filter(Boolean).length !== 1)
+        throw new Error(
+          "Specify exactly one of --artifact-id, --file-token or --source-path"
+        );
+      if (Boolean(ctx.str("sourcePath")) !== Boolean(ctx.str("runId")))
+        throw new Error("--source-path and --run-id must be provided together");
+      return {
+        ...sourceBody(ctx),
+        ...ctx.str("artifactId") ? { artifactId: validThingsId(ctx.str("artifactId")) } : {},
+        ...ctx.str("fileToken") ? { fileToken: ctx.str("fileToken") } : {},
+        ...ctx.str("sourcePath") ? { sourcePath: ctx.str("sourcePath") } : {},
+        destinationPath: ctx.str("destinationPath") || null,
+        role: ctx.str("role") || "attachment",
+        confirmShare: true
+      };
+    }
+  },
+  {
+    command: "conversations",
+    method: "GET",
+    suffix: (ctx) => `/things/${thingId(ctx)}/conversations`,
+    flags: [idFlag, ...pageFlags],
+    params: pageQuery
+  },
+  {
+    command: "link-conversation",
+    method: "POST",
+    suffix: (ctx) => `/things/${thingId(ctx)}/conversations`,
+    flags: [
+      idFlag,
+      {
+        name: "conversation-id",
+        type: "string",
+        required: true,
+        desc: "Owned conversation to reference; does not replace its primary thing"
+      }
+    ],
+    body: (ctx) => ({
+      conversationId: validThingsId(ctx.str("conversationId"))
+    })
+  },
+  {
+    command: "context",
+    method: "GET",
+    suffix: (ctx) => `/things/${thingId(ctx)}/context`,
+    flags: [
+      idFlag,
+      {
+        name: "run-id",
+        type: "string",
+        desc: "Read this execution snapshot; omitted reads live context"
+      }
+    ],
+    params: (ctx) => ctx.str("runId") ? { runId: validThingsId(ctx.str("runId")) } : {}
+  },
+  {
+    command: "list",
+    method: "GET",
+    suffix: () => "/things",
+    flags: [
+      ...pageFlags,
+      {
+        name: "query",
+        type: "string",
+        sensitive: true,
+        desc: "Search title and description"
+      },
+      { name: "status", type: "string", desc: "Filter thing status" },
+      { name: "assignee-id", type: "string", desc: "Filter assignee" }
+    ],
+    params: (ctx) => ({
+      ...pageQuery(ctx),
+      ...Object.fromEntries(
+        ["query", "status", "assigneeId"].flatMap(
+          (k) => ctx.str(k) ? [[k, ctx.str(k)]] : []
+        )
+      )
+    })
+  },
+  {
+    command: "get",
+    method: "GET",
+    suffix: (ctx) => `/things/${thingId(ctx)}`,
+    flags: [idFlag]
+  },
+  {
+    command: "create",
+    method: "POST",
+    suffix: () => "/things",
+    flags: thingFlags,
+    body: (ctx) => {
+      const fields = thingBody(ctx);
+      if (typeof fields.title !== "string" || !fields.title.trim() || typeof fields.description !== "string" || !fields.description.trim())
+        throw new Error("Thing creation requires title and description");
+      return fields;
+    }
+  },
+  {
+    command: "update",
+    method: "PATCH",
+    suffix: (ctx) => `/things/${thingId(ctx)}`,
+    flags: [idFlag, versionFlag, ...thingFlags],
+    body: (ctx) => ({
+      ...thingBody(ctx),
+      expectedVersion: ctx.num("expectedVersion")
+    })
+  },
+  ...["archive", "restore"].map((command) => ({
+    command,
+    method: "POST",
+    suffix: (ctx) => `/things/${thingId(ctx)}/${command}`,
+    flags: [idFlag, versionFlag],
+    body: (ctx) => ({ expectedVersion: ctx.num("expectedVersion") })
+  })),
+  {
+    command: "delete",
+    method: "DELETE",
+    suffix: (ctx) => `/things/${thingId(ctx)}`,
+    flags: [
+      idFlag,
+      versionFlag,
+      {
+        name: "confirm-delete",
+        type: "boolean",
+        desc: "Confirm irreversible deletion of the thing and all links; keep conversations, messages and files"
+      }
+    ],
+    validate: (ctx) => {
+      if (!ctx.bool("confirmDelete"))
+        throw new Error(
+          "Explicit deletion confirmation is required: --confirm-delete"
+        );
+    },
+    body: (ctx) => ({
+      expectedVersion: ctx.num("expectedVersion"),
+      confirmDelete: true
+    })
+  },
+  {
+    resource: "entry",
+    command: "list",
+    method: "GET",
+    suffix: (ctx) => `/things/${thingId(ctx)}/entries`,
+    flags: [idFlag, ...pageFlags],
+    params: pageQuery
+  },
+  {
+    resource: "entry",
+    command: "append",
+    method: "POST",
+    suffix: (ctx) => `/things/${thingId(ctx)}/entries`,
+    flags: [
+      idFlag,
+      {
+        name: "content",
+        type: "string",
+        sensitive: true,
+        desc: "Entry content"
+      },
+      {
+        name: "file",
+        type: "string",
+        sensitive: true,
+        desc: "UTF-8 text file"
+      },
+      { name: "stdin", type: "boolean", desc: "Read text from stdin" },
+      {
+        name: "type",
+        type: "string",
+        desc: "url | note | progress; omitted auto-detects URL or note"
+      },
+      {
+        name: "title",
+        type: "string",
+        sensitive: true,
+        desc: "Entry title, at most 200 characters"
+      }
+    ],
+    validate: (ctx) => {
+      if (ctx.str("type") && !["note", "url", "progress"].includes(ctx.str("type")))
+        throw new Error("Entry type must be note, url or progress");
+      if (ctx.str("title") && !ctx.str("title").trim())
+        throw new Error("Entry title must not be blank");
+      if (ctx.str("title").trim().length > 200)
+        throw new Error("Entry title exceeds 200 characters");
+    },
+    body: (ctx) => {
+      const sources = [
+        Boolean(ctx.str("content")),
+        Boolean(ctx.str("file")),
+        ctx.bool("stdin")
+      ].filter(Boolean).length;
+      if (sources !== 1)
+        throw new Error("Specify exactly one of --content, --file or --stdin");
+      if (ctx.bool("stdin") && process.stdin.isTTY)
+        throw new Error("Pipe text to --stdin");
+      return {
+        ...ctx.str("type") ? { type: ctx.str("type") } : {},
+        ...ctx.str("title") ? { title: ctx.str("title") } : {},
+        content: ctx.str("content") || readFileSync2(ctx.str("file") || 0, "utf8")
+      };
+    }
+  }
+];
+var thingsCommands = actions.map((action) => ({
+  service: "things",
+  resource: action.resource,
+  command: action.command,
+  description: action.resource ? `${action.command} a workspace thing ${action.resource} (Transitional TE REST)` : `${action.command} a workspace thing (Transitional TE REST)`,
+  risk: action.risk ?? (action.method === "GET" ? "read" : action.method === "DELETE" ? "high-risk-write" : "write"),
+  flags: [
+    ...targetFlags,
+    ...action.flags,
+    ...action.method === "GET" ? [] : [commandFlag]
+  ],
+  validate: (ctx) => {
+    thingsTarget(ctx);
+    action.suffix(ctx);
+    action.params?.(ctx);
+    action.validate?.(ctx);
+  },
+  dryRun: (ctx) => {
+    action.validate?.(ctx);
+    return {
+      method: action.method,
+      url: thingsUrl(
+        ctx,
+        `agent-spaces/${thingsTarget(ctx).agentSpaceId ?? "{resolved-space-id}"}${action.suffix(ctx)}`
+      ),
+      params: {
+        target: thingsTarget(ctx),
+        resolveTarget: thingsUrl(ctx, "target"),
+        ...action.params ? { query: "[REDACTED]" } : {}
+      },
+      ...action.body ? {
+        body: {
+          payload: "[REDACTED]",
+          commandId: ctx.str("commandId") || "{generated-uuid}"
+        }
+      } : {}
+    };
+  },
+  execute: async (ctx) => {
+    action.validate?.(ctx);
+    const body = action.body?.(ctx);
+    return requestThings(
+      ctx,
+      action.method,
+      `${await root(ctx)}${action.suffix(ctx)}${query(action.params?.(ctx) ?? {})}`,
+      body ? { ...body, commandId: ctx.str("commandId") || randomUUID() } : void 0
+    );
+  }
+}));
+var scopeFlags = [
+  {
+    name: "thing-ids",
+    type: "string",
+    sensitive: true,
+    desc: "Explicit comma-separated thing IDs; cannot combine with assignee scope"
+  },
+  { name: "assignee-id", type: "string", desc: "Assignee scope" },
+  {
+    name: "from",
+    type: "string",
+    desc: "Inclusive start, ISO timestamp with timezone"
+  },
+  {
+    name: "to",
+    type: "string",
+    desc: "Exclusive end, ISO timestamp with timezone"
+  },
+  {
+    name: "time-zone",
+    type: "string",
+    desc: "Calendar timezone, default Asia/Shanghai"
+  }
+];
+function explicitIds(ctx) {
+  const ids = [
+    ...new Set(
+      ctx.str("thingIds").split(",").map((s) => s.trim()).filter(Boolean).map(validThingsId)
+    )
+  ];
+  if (ids.length > 1e3)
+    throw new Error("At most 1000 explicit thing IDs are supported");
+  if (ids.length && ctx.str("assigneeId"))
+    throw new Error("Use explicit IDs or assignee scope");
+  return ids;
+}
+thingsCommands.push(
+  ...["+detail", "+digest"].map((command) => ({
+    service: "things",
+    command,
+    description: command === "+detail" ? "Collect thing facts and complete timeline with collection boundaries" : "Collect scoped thing facts and period changes for review or summaries",
+    risk: "read",
+    flags: [...targetFlags, ...command === "+detail" ? [idFlag] : scopeFlags],
+    validate: (ctx) => {
+      thingsTarget(ctx);
+      if (command === "+detail") thingId(ctx);
+      else {
+        thingsWindow(ctx);
+        explicitIds(ctx);
+      }
+    },
+    dryRun: (ctx) => ({
+      method: "GET",
+      url: thingsUrl(ctx, "target"),
+      params: {
+        target: thingsTarget(ctx),
+        operation: command,
+        scope: "[REDACTED]",
+        pagination: true
+      }
+    }),
+    execute: async (ctx) => command === "+detail" ? collectThingDetail(ctx, await root(ctx), thingId(ctx)) : collectThingDigest(ctx, await root(ctx), explicitIds(ctx))
+  }))
+);
+var things_default = thingsCommands;
+export {
+  things_default as default,
+  thingBody,
+  thingsCommands,
+  thingsTarget,
+  validThingsId
+};