@robbeverhelst/do 1.164.0 → 1.166.0

package/dist/do.js

@@ -969,7 +969,8 @@ var GLOBAL_BOOLEAN_FLAGS = [
   "help",
   "version",
   "allow-destructive",
-  "dry-run"
+  "dry-run",
+  "draft"
 ];
 var SHORT_ALIASES = {
   h: "help",
@@ -19983,6 +19984,186 @@ var agentFilingSchema = object({
   date: string2().regex(/^\d{4}-\d{2}-\d{2}$/).nullable().optional()
 });
 
+// ../../packages/schema/src/contracts/agent-gateway.ts
+var AGENT_GATEWAY_VERSION = 1;
+var AGENT_GATEWAY_MAX_FRAME_BYTES = 1024 * 1024;
+var threadSlugSchema = string2().regex(/^[a-z0-9][a-z0-9-]{0,39}$/, "a thread slug is lower-case, like `build`");
+var postLevelSchema = _enum2(["needs_you", "told", "for_later", "silent"]);
+var postKindSchema = _enum2(["message", "brief", "card", "run"]);
+var runStatusSchema = _enum2(["running", "needs_you", "done", "failed", "stopped"]);
+var externalIdSchema = string2().min(1).max(200).regex(/^[\x21-\x7e]+$/, "printable ASCII without spaces");
+var AGENT_POST_TEXT_MAX = 64000;
+var postTextSchema = string2().max(AGENT_POST_TEXT_MAX);
+var gatewayMemberSchema = object({
+  id: string2().min(1),
+  name: string2(),
+  role: baseRoleSchema
+});
+var gatewayThreadSchema = object({
+  id: ulidSchema,
+  memberId: string2().min(1),
+  slug: threadSlugSchema.nullable(),
+  title: string2().nullable(),
+  standing: boolean3(),
+  deleted: boolean3().optional()
+});
+var gatewayAttachmentSchema = object({
+  id: ulidSchema,
+  kind: _enum2(["image", "voice", "audio", "video", "file"]),
+  mime: string2().min(1),
+  name: string2(),
+  size: number2().int().nonnegative()
+});
+var inboundMessageSchema = object({
+  id: ulidSchema,
+  threadId: ulidSchema,
+  member: object({ id: string2().min(1), name: string2() }),
+  text: string2(),
+  createdAt: string2().datetime(),
+  attachments: array(gatewayAttachmentSchema).default([]),
+  replyToPostId: ulidSchema.optional(),
+  context: agentPageContextSchema.optional(),
+  history: array(object({ role: _enum2(["member", "agent"]), text: string2() })).optional()
+});
+var threadTargetSchema = union([
+  object({ id: ulidSchema }).strict(),
+  object({ slug: threadSlugSchema, memberId: string2().min(1).optional() }).strict()
+]);
+var postRunSchema = object({ status: runStatusSchema });
+var agentPostInputSchema = object({
+  externalId: externalIdSchema,
+  thread: threadTargetSchema,
+  text: postTextSchema,
+  kind: postKindSchema.default("message"),
+  level: postLevelSchema.nullish(),
+  replyToMessageId: ulidSchema.optional(),
+  attachments: array(ulidSchema).max(20).default([]),
+  final: boolean3().default(true),
+  run: postRunSchema.optional(),
+  recovered: boolean3().optional()
+});
+var agentPostEditSchema = object({
+  text: postTextSchema.optional(),
+  final: boolean3().optional(),
+  level: postLevelSchema.optional(),
+  run: postRunSchema.optional()
+}).refine((e) => Object.values(e).some((v) => v !== undefined), {
+  message: "send text, final, level or run"
+});
+var agentPostResultSchema = object({ postId: ulidSchema, created: boolean3() });
+var promptOptionSchema = object({
+  id: string2().min(1).max(40),
+  label: string2().min(1).max(80),
+  style: _enum2(["primary", "danger", ""]).default("")
+});
+var agentPromptSchema = object({
+  promptId: string2().min(1).max(100),
+  threadId: ulidSchema,
+  kind: _enum2(["exec_approval", "clarify", "slash_confirm"]),
+  text: postTextSchema,
+  options: array(promptOptionSchema).min(1).max(12),
+  allowText: boolean3().default(false),
+  expiresAt: string2().datetime(),
+  command: string2().optional(),
+  description: string2().optional()
+});
+var agentGatewayErrorCodeSchema = _enum2([
+  "bad_request",
+  "not_found",
+  "thread_not_found",
+  "not_member",
+  "too_large",
+  "rate_limited",
+  "unsupported",
+  "internal"
+]);
+var agentGatewayErrorSchema = object({
+  code: agentGatewayErrorCodeSchema,
+  message: string2(),
+  retryable: boolean3()
+});
+var frame = (type, shape) => object({
+  v: literal(AGENT_GATEWAY_VERSION),
+  type: literal(type),
+  id: string2().min(1).max(64),
+  ...shape
+});
+var readyFrameSchema = frame("ready", {
+  space: object({
+    id: string2().min(1),
+    name: string2(),
+    ownerMemberId: string2().min(1)
+  }),
+  agent: object({
+    id: string2().min(1),
+    name: string2(),
+    homeSlug: threadSlugSchema
+  }),
+  members: array(gatewayMemberSchema),
+  threads: array(gatewayThreadSchema),
+  heartbeatSec: number2().int().positive()
+});
+var membersFrameSchema = frame("members", { members: array(gatewayMemberSchema) });
+var threadsFrameSchema = frame("threads", { threads: array(gatewayThreadSchema) });
+var messageFrameSchema = frame("message", { message: inboundMessageSchema });
+var promptAnswerFrameSchema = frame("prompt.answer", {
+  promptId: string2().min(1),
+  optionId: string2().min(1),
+  text: string2().optional(),
+  memberId: string2().min(1),
+  threadId: ulidSchema
+});
+var interruptFrameSchema = frame("interrupt", {
+  threadId: ulidSchema,
+  memberId: string2().min(1)
+});
+var ackFrameSchema = frame("ack", {
+  ref: string2().min(1),
+  ok: boolean3(),
+  postId: ulidSchema.optional(),
+  created: boolean3().optional(),
+  error: agentGatewayErrorSchema.optional()
+});
+var agentGatewayServerFrameSchema = discriminatedUnion("type", [
+  readyFrameSchema,
+  membersFrameSchema,
+  threadsFrameSchema,
+  messageFrameSchema,
+  promptAnswerFrameSchema,
+  interruptFrameSchema,
+  ackFrameSchema
+]);
+var messageAckFrameSchema = frame("message.ack", { messageId: ulidSchema });
+var postFrameSchema = frame("post", { post: agentPostInputSchema });
+var postEditFrameSchema = frame("post.edit", {
+  postId: ulidSchema,
+  edit: agentPostEditSchema
+});
+var postDeleteFrameSchema = frame("post.delete", { postId: ulidSchema });
+var typingFrameSchema = frame("typing", { threadId: ulidSchema, on: boolean3() });
+var promptFrameSchema = frame("prompt", { prompt: agentPromptSchema });
+var promptCloseFrameSchema = frame("prompt.close", {
+  promptId: string2().min(1),
+  optionId: string2().optional(),
+  expired: boolean3()
+});
+var agentGatewayClientFrameSchema = discriminatedUnion("type", [
+  messageAckFrameSchema,
+  postFrameSchema,
+  postEditFrameSchema,
+  postDeleteFrameSchema,
+  typingFrameSchema,
+  promptFrameSchema,
+  promptCloseFrameSchema
+]);
+var SERVER_FRAME_TYPES = new Set(agentGatewayServerFrameSchema.options.map((o) => o.shape.type.value));
+var CLIENT_FRAME_TYPES = new Set(agentGatewayClientFrameSchema.options.map((o) => o.shape.type.value));
+var agentThreadsResponseSchema = object({ threads: array(gatewayThreadSchema) });
+function homeSlugFor(agentName) {
+  const slug = agentName.normalize("NFKD").replace(/[\u0300-\u036F]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
+  return slug || "agent";
+}
+
 // ../../packages/schema/src/contracts/roles.ts
 var permissionSetSchema = createSelectSchema(permissionSets, {
   createdAt: exports_coerce.date(),
@@ -21083,7 +21264,7 @@ function parseCapture2(input, now) {
 
 // src/meta.ts
 var CLI_NAME = "do";
-var VERSION = "1.164.0";
+var VERSION = "1.166.0";
 var API_PREFIX = "/api/v1";
 var DEFAULT_API_URL = "http://localhost:3001";
 
@@ -22357,6 +22538,95 @@ var COMMAND_SPECS = [
     returns: "None",
     notes: "Owner/admin only. An Agent's key gets a 428 confirmation_required until the member confirms in the Echo panel."
   },
+  {
+    path: ["agent", "post"],
+    summary: "Post into a member's thread as the Space's agent (or --edit / --delete a post).",
+    args: [
+      { name: "text", required: false, description: "The text (markdown), or - to read stdin." }
+    ],
+    flags: [
+      {
+        name: "thread",
+        type: "string",
+        description: "The thread: its slug (`build`) or id. Default: the agent's home thread."
+      },
+      {
+        name: "member",
+        type: "string",
+        description: "With a slug: the member whose thread it is (default: the Space's first owner)."
+      },
+      { name: "kind", type: "string", description: "message (default), brief, card or run." },
+      {
+        name: "level",
+        type: "string",
+        description: "needs_you, told, for_later or silent (default by kind: a message told, the rest for_later)."
+      },
+      {
+        name: "external-id",
+        type: "string",
+        description: "Your idempotency key (`card:repos`): the same key again returns the post, and a card is replaced in place. Default: a fresh one."
+      },
+      {
+        name: "draft",
+        type: "boolean",
+        description: "Not final yet (a reply still being edited)."
+      },
+      { name: "edit", type: "string", description: "Edit this post (its id) instead: its text." },
+      { name: "delete", type: "string", description: "Take this post (its id) back." }
+    ],
+    scopes: ["agents:converse"],
+    returns: "AgentPostResult",
+    notes: "Only the Space's agent's key. An unknown slug is thread_not_found (the member makes standing threads); the home slug always works. --edit and --delete act on the agent's own posts."
+  },
+  {
+    path: ["agent", "threads"],
+    summary: "List every member's standing threads (the ones a slug addresses).",
+    args: [],
+    flags: [],
+    scopes: ["agents:converse"],
+    returns: "{ threads: GatewayThread[] }",
+    notes: "Ad-hoc threads aren't listed."
+  },
+  {
+    path: ["echo", "post"],
+    summary: "Same as `agent post`: post into a member's thread as the Space's agent.",
+    args: [
+      { name: "text", required: false, description: "The text (markdown), or - to read stdin." }
+    ],
+    flags: [
+      {
+        name: "thread",
+        type: "string",
+        description: "The thread: its slug (`build`) or id. Default: the agent's home thread."
+      },
+      {
+        name: "member",
+        type: "string",
+        description: "With a slug: the member whose thread it is (default: the Space's first owner)."
+      },
+      { name: "kind", type: "string", description: "message (default), brief, card or run." },
+      {
+        name: "level",
+        type: "string",
+        description: "needs_you, told, for_later or silent (default by kind: a message told, the rest for_later)."
+      },
+      {
+        name: "external-id",
+        type: "string",
+        description: "Your idempotency key (`card:repos`): the same key again returns the post, and a card is replaced in place. Default: a fresh one."
+      },
+      {
+        name: "draft",
+        type: "boolean",
+        description: "Not final yet (a reply still being edited)."
+      },
+      { name: "edit", type: "string", description: "Edit this post (its id) instead: its text." },
+      { name: "delete", type: "string", description: "Take this post (its id) back." }
+    ],
+    scopes: ["agents:converse"],
+    returns: "AgentPostResult",
+    notes: "Only the Space's agent's key. An unknown slug is thread_not_found (the member makes standing threads); the home slug always works. --edit and --delete act on the agent's own posts."
+  },
   {
     path: ["echo", "threads", "list"],
     summary: "List your recent Echo threads, newest first.",
@@ -23718,17 +23988,36 @@ function renderEchoThread(data, mode) {
     return paint(mode, "dim", "No Echo thread yet.");
   const head = `${thread.title ?? "New conversation"}  ${paint(mode, "dim", thread.id ?? "")}`;
   const turns = thread.turns ?? [];
-  if (turns.length === 0)
+  const posts = thread.posts ?? [];
+  if (turns.length === 0 && posts.length === 0) {
     return `${head}
 ${paint(mode, "dim", "(nothing asked yet)")}`;
-  const lines = turns.flatMap((t) => {
-    const note = t.status === "error" ? ` (failed: ${t.error ?? "error"})` : t.status === "cancelled" ? " (stopped)" : t.status === "streaming" ? " (still answering)" : "";
-    return [
-      `  ${paint(mode, "bold", "You")}   ${t.question ?? ""}`,
-      `  ${paint(mode, "bold", "Echo")}  ${t.reply ?? ""}${paint(mode, "dim", note)}`
-    ];
-  });
-  return [head, ...lines].join(`
+  }
+  const entries = [
+    ...turns.map((t, i) => {
+      const note = t.status === "error" ? ` (failed: ${t.error ?? "error"})` : t.status === "cancelled" ? " (stopped)" : t.status === "streaming" ? " (still answering)" : "";
+      return {
+        at: t.createdAt ?? "",
+        order: i,
+        lines: [
+          `  ${paint(mode, "bold", "You")}   ${t.question ?? ""}`,
+          `  ${paint(mode, "bold", "Echo")}  ${t.reply ?? ""}${paint(mode, "dim", note)}`
+        ]
+      };
+    }),
+    ...posts.map((p, i) => {
+      const who = p.author === "member" ? "You" : p.agentName ?? "Agent";
+      const note = [p.kind && p.kind !== "message" ? p.kind : "", p.final === false ? "draft" : ""].filter(Boolean).join(", ");
+      return {
+        at: p.createdAt ?? "",
+        order: turns.length + i,
+        lines: [
+          `  ${paint(mode, "bold", who)}  ${p.text ?? ""}${note ? paint(mode, "dim", ` (${note})`) : ""}`
+        ]
+      };
+    })
+  ].sort((a, b) => a.at === b.at ? a.order - b.order : a.at < b.at ? -1 : 1);
+  return [head, ...entries.flatMap((e) => e.lines)].join(`
 `);
 }
 function actorText(actor) {
@@ -24655,6 +24944,12 @@ var HANDLERS = {
     await requireClient().delete("/agent/connection");
     return { data: { ok: true, removed: "agent connection" }, render: renderRecord };
   },
+  "agent post": agentPost,
+  "echo post": agentPost,
+  "agent threads": async ({ requireClient }) => ({
+    data: await requireClient().get("/agent/threads"),
+    render: renderRecord
+  }),
   "echo threads list": async ({ flags, requireClient }) => ({
     data: await requireClient().getPage("/echo/threads", {
       query: { limit: flagString(flags, "limit") }
@@ -25171,6 +25466,65 @@ async function readAgentKey(io, flags) {
   const fromEnv = io.env[AGENT_KEY_ENV]?.trim();
   return fromEnv ? fromEnv : undefined;
 }
+async function agentPost({ io, args, flags, requireClient }) {
+  const client = requireClient();
+  const remove = flagString(flags, "delete");
+  if (remove !== undefined) {
+    await client.delete(`/agent/posts/${encodeURIComponent(remove)}`);
+    return { data: { ok: true, deleted: remove }, render: renderRecord };
+  }
+  const text = await postText(io, args);
+  const edit = flagString(flags, "edit");
+  if (edit !== undefined) {
+    const body = parseInput(agentPostEditSchema, {
+      text,
+      ...flagBool(flags, "draft") ? { final: false } : {},
+      level: flagString(flags, "level")
+    });
+    return {
+      data: await client.patch(`/agent/posts/${encodeURIComponent(edit)}`, body),
+      render: renderRecord
+    };
+  }
+  const thread = flagString(flags, "thread") ?? await homeSlug(client);
+  const member = flagString(flags, "member");
+  const body = parseInput(agentPostInputSchema, {
+    externalId: flagString(flags, "external-id") ?? `cli:${ulid3()}`,
+    thread: ULID.test(thread) ? { id: thread.toUpperCase() } : { slug: thread, ...member ? { memberId: member } : {} },
+    text,
+    kind: flagString(flags, "kind"),
+    level: flagString(flags, "level"),
+    final: !flagBool(flags, "draft")
+  });
+  return { data: await client.post("/agent/posts", body), render: renderRecord };
+}
+async function postText(io, args) {
+  if (args.length === 1 && args[0] === "-") {
+    const lines = [];
+    if (io.stdin)
+      for await (const line of io.stdin)
+        lines.push(line);
+    const text = lines.join(`
+`).trim();
+    if (!text)
+      throw usageError("read no text from stdin");
+    return text;
+  }
+  const text = args.join(" ").trim();
+  if (!text)
+    throw usageError("agent post needs the text (or - to read it from stdin)");
+  return text;
+}
+async function homeSlug(client) {
+  const me = await client.get("/whoami");
+  if (!me.agentId)
+    throw usageError("this key isn't an Agent's: pass --thread <slug|id>");
+  const { data } = await client.getPage("/agents");
+  const agent = data.find((a) => a.id === me.agentId);
+  if (!agent)
+    throw usageError("couldn't read the agent's name: pass --thread <slug|id>");
+  return homeSlugFor(agent.name);
+}
 var ULID = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
 async function resolveAgentId(client, agent) {
   if (ULID.test(agent))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robbeverhelst/do",
-  "version": "1.164.0",
+  "version": "1.166.0",
   "private": false,
   "description": "do — the agent-drivable CLI over the public /api/v1 surface",
   "homepage": "https://github.com/robbeverhelst/do/tree/main/apps/cli",