@khanglvm/outline-cli 0.1.8 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.0 - 2026-06-23
4
+
5
+ - Changes since `v0.1.8`.
6
+ - feat(comments): ergonomic commenting with @-mentions — `comments.create`/`comments.post` accept plain/markdown `text` and build the Outline ProseMirror `data` doc, resolve `mentions` (names/emails/userIds, first-name + email matching) into mention nodes, enforce the 1000-character text limit pre-flight, and support `parentCommentId` replies; `comments.list` documents `includeReplies`/`parentCommentId` for reading replies.
7
+
3
8
  ## 0.1.8 - 2026-06-11
4
9
 
5
10
  - Changes since `v0.1.7`.
package/README.md CHANGED
@@ -237,11 +237,32 @@ outline-cli invoke comments.list \
237
237
  --args '{"query":"incident runbook","includeReplies":true,"limit":20,"view":"summary"}'
238
238
  ```
239
239
 
240
- Create a comment directly from a remembered document title:
240
+ Create a comment directly from a remembered document title. Pass plain/markdown
241
+ `text` (the ProseMirror `data` doc is built for you) and an optional `mentions`
242
+ list of names, emails, or userIds. Names match on **first name**, so Jira-order
243
+ `"Tran Le Quan"` resolves to Outline's `"Quan, Tran Le"`. The comment text is
244
+ capped at 1000 characters (checked pre-flight). `comments.post` is an alias.
241
245
 
242
246
  ```bash
247
+ # simple comment
243
248
  outline-cli invoke comments.create \
244
249
  --args '{"query":"incident runbook","text":"Looks good.","performAction":true}'
250
+
251
+ # comment with @-mentions (resolved to user IDs and inserted at the start)
252
+ outline-cli invoke comments.create \
253
+ --args '{"query":"incident runbook","text":"Please review the rollback steps.","mentions":["Tran Le Quan","alice@example.com"],"performAction":true}'
254
+
255
+ # reply to an existing comment
256
+ outline-cli invoke comments.post \
257
+ --args '{"documentId":"<doc-id>","parentCommentId":"<comment-id>","text":"Confirmed.","performAction":true}'
258
+ ```
259
+
260
+ Read a comment's replies later with `comments.list` (set `includeReplies:true`,
261
+ or pass `parentCommentId` to fetch one thread's replies):
262
+
263
+ ```bash
264
+ outline-cli invoke comments.list \
265
+ --args '{"query":"incident runbook","includeReplies":true,"view":"summary"}'
245
266
  ```
246
267
 
247
268
  List share links directly from a remembered document title:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@khanglvm/outline-cli",
3
- "version": "0.1.8",
3
+ "version": "0.2.0",
4
4
  "description": "Agent-optimized CLI for Outline API",
5
5
  "type": "module",
6
6
  "bin": {
@@ -737,8 +737,10 @@ const AI_SKILLS = [
737
737
  objective: "Build deterministic review queues and close loops with comment evidence.",
738
738
  featureUpdates: [
739
739
  "comments.review_queue wrapper added for scoped editorial queues.",
740
- "comments.list can resolve remembered document refs for direct thread hydration.",
741
- "comments.create can resolve remembered document refs before creating comments.",
740
+ "comments.list can resolve remembered document refs for direct thread hydration (includeReplies=true to nest replies).",
741
+ "comments.create / comments.post accept plain text and build the ProseMirror data doc for you.",
742
+ "comments.create / comments.post accept mentions (names/emails/userIds) and auto-insert @-mention nodes; names match on first name.",
743
+ "comments.create / comments.post enforce the 1000-character comment limit pre-flight and accept parentCommentId for replies.",
742
744
  "Thread/reply and anchor metadata can be included for full review context.",
743
745
  ],
744
746
  sequence: [
@@ -772,6 +774,7 @@ const AI_SKILLS = [
772
774
  "Scope review_queue to explicit documentIds whenever possible.",
773
775
  "Pass query/refs/url/urlId directly to comments.list when drilling into one remembered document.",
774
776
  "Pass query/refs/url/urlId directly to comments.create when adding an approved comment to a remembered document.",
777
+ "Use comments.create/comments.post with plain text + mentions instead of hand-building ProseMirror data; pass an email or userId when a first name is ambiguous.",
775
778
  "Use limitPerDocument to control queue growth and rerun with cursor-like cadence.",
776
779
  ],
777
780
  safetyChecks: [
@@ -3,8 +3,8 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
3
3
  version: 1,
4
4
  algorithm: "sha256",
5
5
  signatureAlgorithm: "sha256-salted-manifest-v1",
6
- signature: "8b0e982dd0adc3866dcd8c54cda30fc5b989c45c99763f223499a77291309078",
7
- generatedAt: "2026-06-11T03:12:54.187Z",
6
+ signature: "40638ba4d3f763d584f68234f135e58af065f6cb019257ea0a051dc10010e39a",
7
+ generatedAt: "2026-06-23T00:27:13.815Z",
8
8
  files: [
9
9
  {
10
10
  "path": "src/action-gate.js",
@@ -12,7 +12,7 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
12
12
  },
13
13
  {
14
14
  "path": "src/agent-skills.js",
15
- "sha256": "2c067431d98a4574fa7155a8d5952660a893f79b944c6e8750730ad109869e00"
15
+ "sha256": "7da906f5fc1c819311bfdf50719ade949586c9a13cb51c0142fff360eed4ac7f"
16
16
  },
17
17
  {
18
18
  "path": "src/cli.js",
@@ -52,11 +52,11 @@ export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
52
52
  },
53
53
  {
54
54
  "path": "src/tool-arg-schemas.js",
55
- "sha256": "4fe93841790c0a916ff1dcf1b970528afed02ba530b0422560599bb62d575f0e"
55
+ "sha256": "ebc813dd48d5aeb44c655914d504f5ee1ec1ef8205bdec7c5f9adebb3337bd0d"
56
56
  },
57
57
  {
58
58
  "path": "src/tools.extended.js",
59
- "sha256": "69cdbd8e957a566813f8d97b926e0d764c29ce68187140f65c703467b77e8fe3"
59
+ "sha256": "acbd8f5b297c4d4c08e913a710230879e63a230886592823b716bdb5b5cca52d"
60
60
  },
61
61
  {
62
62
  "path": "src/tools.js",
@@ -2954,6 +2954,7 @@ export const TOOL_ARG_SCHEMAS = {
2954
2954
  properties: {
2955
2955
  ...DOCUMENT_TARGET_RESOLVE_PROPERTIES,
2956
2956
  text: { type: "string" },
2957
+ mentions: { type: "string[]" },
2957
2958
  data: { type: "object" },
2958
2959
  parentCommentId: { type: "string" },
2959
2960
  includePolicies: { type: "boolean" },
@@ -2963,8 +2964,29 @@ export const TOOL_ARG_SCHEMAS = {
2963
2964
  },
2964
2965
  custom(args, issues) {
2965
2966
  validateRequiredDocumentResolveArgs(args, issues);
2966
- if (!args.text && !args.data) {
2967
- issues.push({ path: "args.text", message: "or args.data is required" });
2967
+ const hasMentions = Array.isArray(args.mentions) && args.mentions.length > 0;
2968
+ if (!args.text && !args.data && !hasMentions) {
2969
+ issues.push({ path: "args.text", message: "or args.data or args.mentions is required" });
2970
+ }
2971
+ },
2972
+ },
2973
+ "comments.post": {
2974
+ properties: {
2975
+ ...DOCUMENT_TARGET_RESOLVE_PROPERTIES,
2976
+ text: { type: "string" },
2977
+ mentions: { type: "string[]" },
2978
+ data: { type: "object" },
2979
+ parentCommentId: { type: "string" },
2980
+ includePolicies: { type: "boolean" },
2981
+ view: { type: "string", enum: ["summary", "full"] },
2982
+ maxAttempts: { type: "number", min: 1 },
2983
+ performAction: { type: "boolean" },
2984
+ },
2985
+ custom(args, issues) {
2986
+ validateRequiredDocumentResolveArgs(args, issues);
2987
+ const hasMentions = Array.isArray(args.mentions) && args.mentions.length > 0;
2988
+ if (!args.text && !args.data && !hasMentions) {
2989
+ issues.push({ path: "args.text", message: "or args.data or args.mentions is required" });
2968
2990
  }
2969
2991
  },
2970
2992
  },
@@ -1,6 +1,6 @@
1
1
  import fs from "node:fs/promises";
2
2
  import path from "node:path";
3
- import { createHash } from "node:crypto";
3
+ import { createHash, randomUUID } from "node:crypto";
4
4
  import { ApiError, CliError } from "./errors.js";
5
5
  import { assertPerformAction } from "./action-gate.js";
6
6
  import { defaultTmpDir } from "./config-store.js";
@@ -1003,6 +1003,345 @@ async function resolveAccessId(ctx, args = {}, input) {
1003
1003
  };
1004
1004
  }
1005
1005
 
1006
+ // ---------------------------------------------------------------------------
1007
+ // Comment ergonomics: plain/markdown text -> Outline ProseMirror `data` doc,
1008
+ // with first-class @-mention resolution.
1009
+ //
1010
+ // Outline stores comment bodies as a ProseMirror document under `data`, NOT a
1011
+ // plain `text` field (the API returns validation_error if only text is sent on
1012
+ // some deployments, and mentions are impossible without the doc form). Each
1013
+ // mention is a node: { type: "mention", attrs: { type: "user", modelId, label,
1014
+ // id, actorId } } where `id` is a fresh UUID per mention. Outline enforces a
1015
+ // 1000-character limit measured on the comment TEXT (not the JSON), returning
1016
+ // validation_error "Comment must be less than 1000 characters (data)".
1017
+ //
1018
+ // We accept a simple `text` body plus a `mentions` list (names / emails /
1019
+ // userIds) and build the doc ourselves. Mentions are resolved against the
1020
+ // users API by FIRST-NAME token + email (display-name order varies across
1021
+ // systems, e.g. Outline shows "Quan, Tran Le" while Jira shows "Tran Le Quan").
1022
+ // ---------------------------------------------------------------------------
1023
+
1024
+ const COMMENT_TEXT_LIMIT = 1000;
1025
+
1026
+ function commentTextNode(text) {
1027
+ return { type: "text", text };
1028
+ }
1029
+
1030
+ function commentMentionNode({ userId, label }) {
1031
+ return {
1032
+ type: "mention",
1033
+ attrs: {
1034
+ type: "user",
1035
+ modelId: userId,
1036
+ label: label || "user",
1037
+ id: randomUUID(),
1038
+ actorId: null,
1039
+ },
1040
+ };
1041
+ }
1042
+
1043
+ // Split plain/markdown text into paragraphs on blank lines, and keep single
1044
+ // newlines as hard breaks inside a paragraph (mirrors how a human pastes text).
1045
+ function splitCommentParagraphs(text) {
1046
+ const normalized = String(text == null ? "" : text).replace(/\r\n?/g, "\n");
1047
+ const blocks = normalized.split(/\n{2,}/);
1048
+ const paragraphs = [];
1049
+ for (const block of blocks) {
1050
+ if (block.trim().length === 0) {
1051
+ continue;
1052
+ }
1053
+ paragraphs.push(block.split("\n"));
1054
+ }
1055
+ return paragraphs;
1056
+ }
1057
+
1058
+ // Build the ProseMirror `data` doc for a comment from text + resolved mentions.
1059
+ // Resolved mentions (each { userId, label }) are inserted at the very start of
1060
+ // the first paragraph, followed by a space, then the text.
1061
+ function buildCommentData(text, resolvedMentions = []) {
1062
+ const paragraphs = splitCommentParagraphs(text);
1063
+ const mentionNodes = resolvedMentions.map((mention) => commentMentionNode(mention));
1064
+
1065
+ const content = [];
1066
+ if (paragraphs.length === 0 && mentionNodes.length === 0) {
1067
+ content.push({ type: "paragraph" });
1068
+ }
1069
+
1070
+ paragraphs.forEach((lines, paragraphIndex) => {
1071
+ const inline = [];
1072
+ if (paragraphIndex === 0 && mentionNodes.length > 0) {
1073
+ mentionNodes.forEach((node) => {
1074
+ inline.push(node);
1075
+ inline.push(commentTextNode(" "));
1076
+ });
1077
+ }
1078
+ lines.forEach((line, lineIndex) => {
1079
+ if (lineIndex > 0) {
1080
+ inline.push({ type: "br" });
1081
+ }
1082
+ if (line.length > 0) {
1083
+ inline.push(commentTextNode(line));
1084
+ }
1085
+ });
1086
+ content.push(inline.length > 0 ? { type: "paragraph", content: inline } : { type: "paragraph" });
1087
+ });
1088
+
1089
+ // Mentions with no text body at all: emit a single paragraph holding them.
1090
+ if (paragraphs.length === 0 && mentionNodes.length > 0) {
1091
+ const inline = [];
1092
+ mentionNodes.forEach((node, index) => {
1093
+ inline.push(node);
1094
+ if (index < mentionNodes.length - 1) {
1095
+ inline.push(commentTextNode(" "));
1096
+ }
1097
+ });
1098
+ content.push({ type: "paragraph", content: inline });
1099
+ }
1100
+
1101
+ return { type: "doc", content };
1102
+ }
1103
+
1104
+ // Character count of the human-readable comment text (mention labels count as
1105
+ // "@label", matching how Outline measures the 1000-char limit on the data doc).
1106
+ function commentTextLength(text, resolvedMentions = []) {
1107
+ const textLen = String(text == null ? "" : text).length;
1108
+ const mentionLen = resolvedMentions.reduce(
1109
+ (sum, mention) => sum + 1 + String(mention.label || "user").length + 1,
1110
+ 0
1111
+ );
1112
+ return textLen + mentionLen;
1113
+ }
1114
+
1115
+ function firstNameToken(name) {
1116
+ return String(name || "")
1117
+ // "Last, First Middle" -> take the part after the comma first
1118
+ .split(",")
1119
+ .map((part) => part.trim())
1120
+ .filter(Boolean)
1121
+ .reverse()[0]
1122
+ ?.split(/\s+/)
1123
+ .filter(Boolean)[0]
1124
+ ?.toLowerCase() || "";
1125
+ }
1126
+
1127
+ function normalizeMentionToken(value) {
1128
+ return String(value || "").trim().toLowerCase();
1129
+ }
1130
+
1131
+ function looksLikeUuid(value) {
1132
+ return /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(
1133
+ String(value || "").trim()
1134
+ );
1135
+ }
1136
+
1137
+ function looksLikeEmail(value) {
1138
+ return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value || "").trim());
1139
+ }
1140
+
1141
+ // Pull the user rows out of a users.list response body (shape: { data: [...] }).
1142
+ function usersFromListBody(body) {
1143
+ if (Array.isArray(body)) {
1144
+ return body;
1145
+ }
1146
+ if (Array.isArray(body?.data)) {
1147
+ return body.data;
1148
+ }
1149
+ if (Array.isArray(body?.data?.users)) {
1150
+ return body.data.users;
1151
+ }
1152
+ return [];
1153
+ }
1154
+
1155
+ async function fetchWorkspaceUsers(ctx, { maxAttempts } = {}) {
1156
+ const collected = [];
1157
+ const limit = 100;
1158
+ let offset = 0;
1159
+ // Outline paginates users.list; pull a few pages to cover typical workspaces.
1160
+ for (let page = 0; page < 25; page += 1) {
1161
+ let res;
1162
+ try {
1163
+ res = await ctx.client.call("users.list", { limit, offset }, { maxAttempts: maxAttempts || 2 });
1164
+ } catch (err) {
1165
+ if (collected.length > 0) {
1166
+ break;
1167
+ }
1168
+ throw err;
1169
+ }
1170
+ const rows = usersFromListBody(res.body);
1171
+ collected.push(...rows);
1172
+ const pagination = res.body?.pagination;
1173
+ const total = Number(pagination?.total);
1174
+ if (rows.length < limit) {
1175
+ break;
1176
+ }
1177
+ offset += limit;
1178
+ if (Number.isFinite(total) && offset >= total) {
1179
+ break;
1180
+ }
1181
+ }
1182
+ return collected;
1183
+ }
1184
+
1185
+ // Resolve one mention token (name / email / userId) to { userId, label }.
1186
+ // Matching strategy:
1187
+ // - userId (uuid) -> exact id match
1188
+ // - email -> exact email match
1189
+ // - name -> FIRST-NAME token match (+ optional email disambiguation)
1190
+ // Returns { resolved } on success, or { error, candidates } on failure.
1191
+ function resolveMentionToken(token, users) {
1192
+ const raw = String(token || "").trim();
1193
+ if (!raw) {
1194
+ return { error: { value: token, status: "empty" } };
1195
+ }
1196
+
1197
+ if (looksLikeUuid(raw)) {
1198
+ const match = users.find((user) => normalizeMentionToken(user?.id) === normalizeMentionToken(raw));
1199
+ if (match) {
1200
+ return { resolved: { userId: match.id, label: match.name || match.email || "user" } };
1201
+ }
1202
+ return { error: { value: raw, status: "not_found", reason: "no user with that id" } };
1203
+ }
1204
+
1205
+ if (looksLikeEmail(raw)) {
1206
+ const match = users.find((user) => normalizeMentionToken(user?.email) === normalizeMentionToken(raw));
1207
+ if (match) {
1208
+ return { resolved: { userId: match.id, label: match.name || match.email || "user" } };
1209
+ }
1210
+ return { error: { value: raw, status: "not_found", reason: "no user with that email" } };
1211
+ }
1212
+
1213
+ // Name token: match on first-name token. Support "name <email>" / "name|email".
1214
+ const emailHint = raw.match(/[<|]\s*([^\s@<>|]+@[^\s@<>|]+)\s*>?/)?.[1];
1215
+ const namePart = emailHint ? raw.replace(/[<|]\s*[^\s@<>|]+@[^\s@<>|]+\s*>?/, "").trim() : raw;
1216
+ const wantFirst = firstNameToken(namePart);
1217
+
1218
+ let candidates = users.filter((user) => {
1219
+ const userFirst = firstNameToken(user?.name) || firstNameToken(user?.email);
1220
+ return userFirst && wantFirst && userFirst === wantFirst;
1221
+ });
1222
+
1223
+ if (emailHint) {
1224
+ const byEmail = candidates.filter(
1225
+ (user) => normalizeMentionToken(user?.email) === normalizeMentionToken(emailHint)
1226
+ );
1227
+ if (byEmail.length > 0) {
1228
+ candidates = byEmail;
1229
+ }
1230
+ }
1231
+
1232
+ if (candidates.length === 1) {
1233
+ const match = candidates[0];
1234
+ return { resolved: { userId: match.id, label: match.name || match.email || "user" } };
1235
+ }
1236
+
1237
+ if (candidates.length === 0) {
1238
+ return { error: { value: raw, status: "not_found", reason: "no user matched first name" } };
1239
+ }
1240
+
1241
+ return {
1242
+ error: {
1243
+ value: raw,
1244
+ status: "ambiguous",
1245
+ reason: "multiple users share that first name; pass an email or userId",
1246
+ candidates: candidates.map((user) => ({ id: user.id, name: user.name, email: user.email })),
1247
+ },
1248
+ };
1249
+ }
1250
+
1251
+ async function resolveMentions(ctx, mentions, { maxAttempts } = {}) {
1252
+ const tokens = ensureStringArray(mentions).map((item) => String(item).trim()).filter(Boolean);
1253
+ if (tokens.length === 0) {
1254
+ return { resolved: [], failures: [] };
1255
+ }
1256
+ const users = await fetchWorkspaceUsers(ctx, { maxAttempts });
1257
+ const resolved = [];
1258
+ const failures = [];
1259
+ for (const token of tokens) {
1260
+ const outcome = resolveMentionToken(token, users);
1261
+ if (outcome.resolved) {
1262
+ resolved.push(outcome.resolved);
1263
+ } else {
1264
+ failures.push(outcome.error);
1265
+ }
1266
+ }
1267
+ return { resolved, failures };
1268
+ }
1269
+
1270
+ // prepareBody hook for comments.create / comments.post. Runs AFTER document
1271
+ // resolution (so bodyArgs.documentId is set) and BEFORE the API call. Builds
1272
+ // the ProseMirror `data` doc from `text` + `mentions`, enforces the 1000-char
1273
+ // limit, and strips the convenience-only keys from the outgoing body.
1274
+ async function prepareCommentBody(ctx, def, args, bodyArgs) {
1275
+ const text = typeof bodyArgs.text === "string" ? bodyArgs.text : "";
1276
+ const hasMentions = Array.isArray(args.mentions) && args.mentions.length > 0;
1277
+ const hasExplicitData = bodyArgs.data !== undefined && bodyArgs.data !== null;
1278
+
1279
+ // Caller passed a pre-built ProseMirror doc and no mentions: passthrough,
1280
+ // just drop the convenience-only `mentions` key if present.
1281
+ if (hasExplicitData && !hasMentions && !text) {
1282
+ delete bodyArgs.mentions;
1283
+ return bodyArgs;
1284
+ }
1285
+
1286
+ let resolvedMentions = [];
1287
+ if (hasMentions) {
1288
+ const maxAttempts = toInteger(args.maxAttempts, 2);
1289
+ const { resolved, failures } = await resolveMentions(ctx, args.mentions, { maxAttempts });
1290
+ if (failures.length > 0) {
1291
+ throw new CliError(
1292
+ `comments.${def.tool.endsWith(".post") ? "post" : "create"}: could not resolve ${failures.length} mention(s): ` +
1293
+ failures.map((f) => `"${f.value}" (${f.status})`).join(", "),
1294
+ {
1295
+ code: "MENTION_UNRESOLVED",
1296
+ tool: def.tool,
1297
+ failures,
1298
+ }
1299
+ );
1300
+ }
1301
+ resolvedMentions = resolved;
1302
+ }
1303
+
1304
+ // Enforce the 1000-char limit on the human text (not the JSON), pre-flight.
1305
+ const length = commentTextLength(text, resolvedMentions);
1306
+ if (length > COMMENT_TEXT_LIMIT) {
1307
+ throw new CliError(
1308
+ `comments.${def.tool.endsWith(".post") ? "post" : "create"}: comment text is ${length} characters; Outline allows at most ${COMMENT_TEXT_LIMIT}.`,
1309
+ {
1310
+ code: "COMMENT_TOO_LONG",
1311
+ tool: def.tool,
1312
+ length,
1313
+ limit: COMMENT_TEXT_LIMIT,
1314
+ }
1315
+ );
1316
+ }
1317
+
1318
+ // If the caller gave an explicit data doc AND mentions, prepend mention nodes
1319
+ // to its first paragraph; otherwise build from text.
1320
+ if (hasExplicitData && resolvedMentions.length > 0) {
1321
+ const doc = bodyArgs.data;
1322
+ const mentionNodes = resolvedMentions.flatMap((mention) => [
1323
+ commentMentionNode(mention),
1324
+ commentTextNode(" "),
1325
+ ]);
1326
+ const firstParagraph = Array.isArray(doc?.content)
1327
+ ? doc.content.find((node) => node?.type === "paragraph")
1328
+ : null;
1329
+ if (firstParagraph) {
1330
+ firstParagraph.content = [...mentionNodes, ...(firstParagraph.content || [])];
1331
+ } else if (doc && Array.isArray(doc.content)) {
1332
+ doc.content.unshift({ type: "paragraph", content: mentionNodes });
1333
+ }
1334
+ bodyArgs.data = doc;
1335
+ } else if (!hasExplicitData) {
1336
+ bodyArgs.data = buildCommentData(text, resolvedMentions);
1337
+ }
1338
+
1339
+ // Outline wants `data`, not `text` — drop the convenience keys.
1340
+ delete bodyArgs.text;
1341
+ delete bodyArgs.mentions;
1342
+ return bodyArgs;
1343
+ }
1344
+
1006
1345
  function makeRpcHandler(def) {
1007
1346
  return async function rpcHandler(ctx, args = {}) {
1008
1347
  if (def.mutating) {
@@ -1049,6 +1388,12 @@ function makeRpcHandler(def) {
1049
1388
  omitKeys.push(...(item.omitKeys || []));
1050
1389
  }
1051
1390
  const effectiveOmitKeys = omitKeys.filter((key) => !resolvedOutputFields.has(key));
1391
+ if (typeof def.prepareBody === "function") {
1392
+ // Hook runs after target resolution (documentId is set) and before the
1393
+ // API call, letting a def transform the outgoing body (e.g. comments
1394
+ // build a ProseMirror data doc + resolve @-mentions).
1395
+ await def.prepareBody(ctx, def, args, bodyArgs);
1396
+ }
1052
1397
  const body = buildBody(
1053
1398
  bodyArgs,
1054
1399
  effectiveOmitKeys.length > 0
@@ -1300,7 +1645,24 @@ const RPC_WRAPPER_DEFS = [
1300
1645
  {
1301
1646
  tool: "comments.list",
1302
1647
  method: "comments.list",
1303
- description: "List comments, optionally resolving a remembered document first.",
1648
+ description:
1649
+ "List comments on a document (and their replies). Resolve the target with documentId/query/refs/url/urlId. Use includeReplies=true to nest replies, or parentCommentId to fetch the replies of one thread.",
1650
+ signature:
1651
+ "comments.list(args?: { documentId?: string; query?: string; documentQuery?: string; refs?: string[]; shareId?: string; urlId?: string; url?: string; parentCommentId?: string; includeReplies?: boolean; includeAnchorText?: boolean; limit?: number; offset?: number; sort?: string; direction?: 'ASC'|'DESC'; includePolicies?: boolean; view?: 'ids'|'summary'|'full'; maxAttempts?: number })",
1652
+ usageExample: {
1653
+ tool: "comments.list",
1654
+ args: {
1655
+ query: "incident runbook",
1656
+ includeReplies: true,
1657
+ limit: 50,
1658
+ },
1659
+ },
1660
+ bestPractices: [
1661
+ "Pass documentId for exact calls, or query/refs/url/urlId to resolve a remembered document first.",
1662
+ "Set includeReplies=true to fetch replies nested under each top-level comment.",
1663
+ "Pass parentCommentId to read the replies of a specific comment (e.g. after posting one).",
1664
+ "Use view='ids' or 'summary' to keep responses token-efficient.",
1665
+ ],
1304
1666
  resolveAccess: {
1305
1667
  kind: "document",
1306
1668
  outputField: "documentId",
@@ -1314,24 +1676,62 @@ const RPC_WRAPPER_DEFS = [
1314
1676
  {
1315
1677
  tool: "comments.create",
1316
1678
  method: "comments.create",
1317
- description: "Create a comment on a document ID or remembered document reference.",
1679
+ description:
1680
+ "Post a comment on a document. Pass plain/markdown `text` and the ProseMirror `data` doc is built for you; pass `mentions` (names/emails/userIds) to auto-insert @-mentions. Use `parentCommentId` to reply.",
1318
1681
  signature:
1319
- "comments.create(args: { documentId?: string; query?: string; documentQuery?: string; refs?: string[]; shareId?: string; urlId?: string; url?: string; text?: string; data?: object; parentCommentId?: string; includePolicies?: boolean; view?: 'summary'|'full'; maxAttempts?: number; performAction?: boolean })",
1682
+ "comments.create(args: { documentId?: string; query?: string; documentQuery?: string; refs?: string[]; shareId?: string; urlId?: string; url?: string; text?: string; mentions?: string[]; data?: object; parentCommentId?: string; includePolicies?: boolean; view?: 'summary'|'full'; maxAttempts?: number; performAction?: boolean })",
1320
1683
  usageExample: {
1321
1684
  tool: "comments.create",
1322
1685
  args: {
1323
1686
  query: "incident runbook",
1324
- text: "Looks good.",
1687
+ text: "Please review the rollback steps.",
1688
+ mentions: ["Tran Le Quan", "alice@example.com"],
1689
+ performAction: true,
1690
+ },
1691
+ },
1692
+ bestPractices: [
1693
+ "Pass plain/markdown `text`; the ProseMirror `data` doc is built for you (blank lines split paragraphs, single newlines become line breaks).",
1694
+ "Pass `mentions` as a list of names, emails, or userIds; names match on FIRST NAME (e.g. \"Tran Le Quan\" matches Outline's \"Quan, Tran Le\"). Ambiguous names are rejected with candidates — disambiguate with an email or userId.",
1695
+ "Comment text is capped at 1000 characters (pre-flight check on text, not JSON).",
1696
+ "Pass query/refs/url/urlId to comment on a remembered document without a separate lookup.",
1697
+ "Use parentCommentId to reply to an existing comment.",
1698
+ "Advanced: pass a raw ProseMirror `data` doc to bypass text building (mentions are still prepended if provided).",
1699
+ "This tool is action-gated; set performAction=true only for explicitly confirmed mutations.",
1700
+ ],
1701
+ mutating: true,
1702
+ prepareBody: prepareCommentBody,
1703
+ resolveAccess: {
1704
+ kind: "document",
1705
+ outputField: "documentId",
1706
+ exactKeys: ["documentId"],
1707
+ required: true,
1708
+ queryKeys: ["query", "documentQuery", "documentRef", "shareId", "urlId", "url"],
1709
+ arrayQueryKeys: ["queries", "documentQueries", "documentRefs", "refs", "shareIds", "urlIds", "urls"],
1710
+ },
1711
+ },
1712
+ {
1713
+ tool: "comments.post",
1714
+ method: "comments.create",
1715
+ description:
1716
+ "Convenience alias of comments.create: post a comment from plain `text` + ergonomic `mentions`. The ProseMirror data doc and @-mention nodes are built for you.",
1717
+ signature:
1718
+ "comments.post(args: { documentId?: string; query?: string; documentQuery?: string; refs?: string[]; shareId?: string; urlId?: string; url?: string; text?: string; mentions?: string[]; data?: object; parentCommentId?: string; includePolicies?: boolean; view?: 'summary'|'full'; maxAttempts?: number; performAction?: boolean })",
1719
+ usageExample: {
1720
+ tool: "comments.post",
1721
+ args: {
1722
+ query: "incident runbook",
1723
+ text: "Can you confirm the timeline?",
1724
+ mentions: ["Quan"],
1325
1725
  performAction: true,
1326
1726
  },
1327
1727
  },
1328
1728
  bestPractices: [
1329
- "Pass query/refs/url/urlId when adding a comment to a remembered document without a separate lookup.",
1330
- "Use parentCommentId for replies and text for simple comments.",
1331
- "Inspect the returned documentId and resolution fields when the target was resolved from memory.",
1729
+ "Same as comments.create: simple `text` + `mentions` (names/emails/userIds), 1000-char limit, parentCommentId for replies.",
1730
+ "Names resolve on FIRST NAME + email; ambiguous names error with candidates.",
1332
1731
  "This tool is action-gated; set performAction=true only for explicitly confirmed mutations.",
1333
1732
  ],
1334
1733
  mutating: true,
1734
+ prepareBody: prepareCommentBody,
1335
1735
  resolveAccess: {
1336
1736
  kind: "document",
1337
1737
  outputField: "documentId",
@@ -5357,6 +5757,18 @@ async function federatedPermissionSnapshotTool(ctx, args = {}) {
5357
5757
  };
5358
5758
  }
5359
5759
 
5760
+ // Exported for unit testing the comment data-builder and mention-resolver
5761
+ // without hitting the network.
5762
+ export const __commentInternals = {
5763
+ COMMENT_TEXT_LIMIT,
5764
+ buildCommentData,
5765
+ commentTextLength,
5766
+ splitCommentParagraphs,
5767
+ firstNameToken,
5768
+ resolveMentionToken,
5769
+ usersFromListBody,
5770
+ };
5771
+
5360
5772
  export const EXTENDED_TOOLS = {
5361
5773
  ...RPC_TOOLS,
5362
5774
  "documents.answer": {