@stage5/lumine 0.2.98 → 0.3.0

package/lib/admin.js

@@ -640,6 +640,8 @@ export async function adminCommand(options) {
   let runScope = null;
   let correctionSessionId = 0;
   let correctionSession = null;
+  let commentSessionId = 0;
+  let commentSession = null;
   if (adminOperationRequiresRun(operation)) {
     if (operation.correctionEligible) {
       const correctionStatus = await requestJson({
@@ -657,6 +659,15 @@ export async function adminCommand(options) {
         correctionSession = correction;
       }
     }
+    if (!correctionSessionId && adminOperationUsesCommentSession(operation)) {
+      commentSession = await loadActiveCommentSession({
+        options,
+        authToken: auth.token,
+      });
+      commentSessionId = Number(commentSession?.id || 0);
+    }
+    // Look up the daily run too: when both are active the caller must choose
+    // one (--via), and exactly one authority is sent.
     const runStatus = correctionSessionId
       ? null
       : await requestJson({
@@ -671,9 +682,39 @@ export async function adminCommand(options) {
     ].includes(operation.name)
       ? runStatus?.data?.lastRun || null
       : null;
-    const selectedRun = activeRun || retryableFinishedRun;
+    let selectedRun = activeRun || retryableFinishedRun;
+    const via = parseAdminVia(options.adminVia, operation);
+    if (via && correctionSessionId) {
+      throw cliValidationError(
+        `Correction session #${correctionSessionId} is active for this comment and handles it; drop --via or complete the correction first.`,
+      );
+    }
+    if (commentSessionId && selectedRun) {
+      let choice = via;
+      if (!choice) {
+        if (COMMENT_SESSION_WRITE_OPERATIONS.has(operation.name)) {
+          throw cliValidationError(
+            `Both comment session #${commentSessionId} (${commentSession.identity?.key || "unknown"}) and daily run #${selectedRun.id} (${selectedRun.identity?.key || "unknown"}) are active. Choose which one this ${operation.name} uses with --via session or --via run.`,
+          );
+        }
+        // Reads create nothing; without --via they keep using the daily run.
+        choice = "run";
+      }
+      if (choice === "session") {
+        selectedRun = null;
+      } else {
+        commentSessionId = 0;
+        commentSession = null;
+      }
+    } else if (via === "session" && !commentSessionId) {
+      throw cliValidationError(
+        "--via session: no comment session is active. Start one with lumine admin comment session start.",
+      );
+    } else if (via === "run" && !selectedRun && !correctionSessionId) {
+      throw noActiveRunError();
+    }
     runId = Number(selectedRun?.id || 0);
-    if (!runId && !correctionSessionId) {
+    if (!runId && !correctionSessionId && !commentSessionId) {
       if (operation.correctionEligible) {
         const error = new Error(
           `Start a correction session first: lumine admin correction start ${operation.correctionCommentId}.`,
@@ -687,7 +728,17 @@ export async function adminCommand(options) {
       runScope = canonicalAdminRunScope(selectedRun);
       assertAdminOperationAllowedForRunScope({ operation, runScope });
     }
-    if (options.adminIdentity && (selectedRun || correctionSession)) {
+    if (options.adminIdentity && commentSession) {
+      const requestedIdentity = parseIdentity(options.adminIdentity);
+      if (
+        requestedIdentity !== "auto" &&
+        requestedIdentity !== commentSession.identity?.key
+      ) {
+        throw cliValidationError(
+          `--identity ${requestedIdentity} does not match comment session #${commentSessionId} (${commentSession.identity?.key || "unknown"}).`,
+        );
+      }
+    } else if (options.adminIdentity && (selectedRun || correctionSession)) {
       const requestedIdentity = parseIdentity(options.adminIdentity);
       const canonicalIdentity = correctionSession
         ? correctionSession.identity?.key
@@ -722,6 +773,11 @@ export async function adminCommand(options) {
                   String(correctionSessionId),
               }
             : {}),
+          ...(commentSessionId
+            ? {
+                "x-lumine-admin-comment-session-id": String(commentSessionId),
+              }
+            : {}),
           ...(requestId ? { "x-lumine-idempotency-key": requestId } : {}),
         },
         // Long operations (reward-bank seed) carry their own timeout.
@@ -1529,6 +1585,81 @@ export function assertAdminOperationAllowedForRunScope({
   );
 }
 
+// Commands a standalone comment session can serve: drafting, replying,
+// publishing and editing its own comments, plus the reads needed to compose
+// on its targets. The API still enforces the session's target lock on each.
+const COMMENT_SESSION_WRITE_OPERATIONS = new Set([
+  "comment.draft",
+  "comment.post",
+  "comment.edit",
+]);
+const COMMENT_SESSION_OPERATIONS = new Set([
+  ...COMMENT_SESSION_WRITE_OPERATIONS,
+  "subject.get",
+  "subject.comments",
+  "post.get",
+  "post.comments",
+]);
+
+export function adminOperationUsesCommentSession(operation) {
+  return COMMENT_SESSION_OPERATIONS.has(operation?.name);
+}
+
+export function parseAdminVia(value, operation) {
+  const via = String(value || "").trim().toLowerCase();
+  if (!via) return "";
+  if (via !== "session" && via !== "run") {
+    throw cliValidationError("--via must be session or run.");
+  }
+  if (!adminOperationUsesCommentSession(operation)) {
+    throw cliValidationError(
+      "--via applies only to comment draft/reply/post/edit and the subject/post/comment reads.",
+    );
+  }
+  return via;
+}
+
+async function loadActiveCommentSession({ options, authToken }) {
+  let status;
+  try {
+    status = await requestJson({
+      url: `${options.apiUrl}/cli/admin/comment-sessions/status`,
+      authToken,
+      timeoutMs: options.timeoutMs,
+    });
+  } catch (error) {
+    // An API without comment sessions yet: keep daily runs working.
+    if (error?.status === 404) return null;
+    throw error;
+  }
+  const session = status?.data?.commentSession || null;
+  return session?.status === "active" && Number(session.id) > 0
+    ? session
+    : null;
+}
+
+export function parseCommentSessionTargets(values) {
+  const raw = values
+    .flatMap((value) => String(value || "").split(","))
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (!raw.length) {
+    throw cliValidationError(
+      "Name the targets with --target <subject:ID|comment:ID|build:ID|aiStory:ID|dailyReflection:ID>[,...].",
+    );
+  }
+  const seen = new Set();
+  const targets = [];
+  for (const value of raw) {
+    const target = parseAdminCommentTarget({ target: value });
+    const key = `${target.type}:${target.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    targets.push(target);
+  }
+  return targets;
+}
+
 function adminOperationRequiresRun(operation) {
   if (typeof operation.requiresRun === "boolean") {
     return operation.requiresRun;
@@ -1547,6 +1678,9 @@ function adminOperationRequiresRun(operation) {
       "correction.start",
       "correction.status",
       "correction.complete",
+      "comment-session.start",
+      "comment-session.status",
+      "comment-session.close",
       "escalation.list",
       "escalation.set",
       "notable.add",
@@ -1935,6 +2069,44 @@ export function parseAdminOperation(options) {
     if (note.length > 1000) {
       throw cliValidationError("--note must be at most 1000 characters.");
     }
+    if (action === "story" || action === "stories") {
+      // A crew's Bridge Builder story page: Mikey's final approval (the
+      // admin bar on the story page does the same). Publishing copies only
+      // the photos/clips every tagged member's parent allowed.
+      const storyUsage =
+        "Usage: lumine admin meetup story list | show <crewId> | approve <crewId> [--note <text>] [--no-announce] | send-back <crewId> --note <text> | unpublish <crewId> --note <text>.";
+      const storyAction = target || "list";
+      if (storyAction === "list") {
+        return readOperation("meetup.story.list", "/cli/admin/meetup-quest/stories", {
+          requiresRun: false,
+        });
+      }
+      if (!["show", "approve", "send-back", "unpublish"].includes(storyAction)) {
+        throw cliValidationError(storyUsage);
+      }
+      const crewId = parseRequiredInteger(extra, "Crew ID", 1);
+      if (storyAction === "show") {
+        return readOperation(
+          "meetup.story.show",
+          `/cli/admin/meetup-quest/stories/by-crew/${crewId}`,
+          { requiresRun: false },
+        );
+      }
+      if (storyAction !== "approve" && !note) {
+        throw cliValidationError(
+          `lumine admin meetup story ${storyAction} <crewId> needs --note <text> (the crew sees it).`,
+        );
+      }
+      return writeOperation(
+        `meetup.story.${storyAction}`,
+        "POST",
+        `/cli/admin/meetup-quest/stories/by-crew/${crewId}/${storyAction}`,
+        storyAction === "approve"
+          ? { note, announce: !options.adminNoAnnounce }
+          : { note },
+        { requiresRun: false },
+      );
+    }
     if (!action || action === "list") {
       return readOperation(
         "meetup.list",
@@ -3323,6 +3495,51 @@ export function parseAdminOperation(options) {
   }
 
   if (namespace === "comment") {
+    if (action === "session") {
+      const sessionAction = target || "status";
+      if (sessionAction === "status") {
+        return readOperation(
+          "comment-session.status",
+          "/cli/admin/comment-sessions/status",
+        );
+      }
+      if (sessionAction === "start") {
+        const identity = String(options.adminIdentity || "")
+          .trim()
+          .toLowerCase();
+        if (identity !== "zero" && identity !== "ciel") {
+          throw cliValidationError(
+            "comment session start needs --identity zero|ciel.",
+          );
+        }
+        const targets = parseCommentSessionTargets([
+          options.adminTarget,
+          ...(options.positional || []).slice(3),
+        ]);
+        const reason = String(options.adminReason || "").trim();
+        return writeOperation(
+          "comment-session.start",
+          "POST",
+          "/cli/admin/comment-sessions",
+          {
+            identity,
+            targets,
+            ...(reason ? { reason } : {}),
+          },
+        );
+      }
+      if (sessionAction === "close") {
+        return writeOperation(
+          "comment-session.close",
+          "POST",
+          "/cli/admin/comment-sessions/close",
+          {},
+        );
+      }
+      throw cliValidationError(
+        "Usage: lumine admin comment session start --identity zero|ciel --target <type:id>[,<type:id>...] [--reason <text>] | comment session status | comment session close.",
+      );
+    }
     if (action === "draft" || action === "reply") {
       const parsedTarget = parseAdminCommentTarget({
         target,
@@ -4892,6 +5109,49 @@ function printMeetupCrew(crew) {
 }
 
 function printMeetupResult({ operation, data, result }) {
+  if (operation.name === "meetup.story.list") {
+    const stories = Array.isArray(data.stories) ? data.stories : [];
+    console.log(`${stories.length} Bridge Builder stor${stories.length === 1 ? "y" : "ies"} waiting for approval:`);
+    for (const story of stories) {
+      console.log(
+        `  crew #${story.crewId} · "${story.title}" · ${story.crewName} (${(story.people || []).join(", ")}) · ${story.itemsPublic} public / ${story.itemsPrivate} private`,
+      );
+    }
+    if (stories.length) console.log("Approve: lumine admin meetup story approve <crewId> (or send-back <crewId> --note).");
+    return;
+  }
+  if (operation.name === "meetup.story.show") {
+    const story = data.story || {};
+    const items = [...(story.photos || []), ...(story.clips || [])];
+    console.log(`Story #${story.storyId} (crew #${story.crewId}) · ${story.status} · "${story.title}"`);
+    console.log(`  People: ${(story.people || []).map((p) => `${p.username} (${p.branch})`).join(", ")}`);
+    for (const consent of story.review?.consents || []) {
+      const person = (story.people || []).find((p) => p.userId === consent.userId);
+      console.log(`  Parent of ${person?.username || consent.userId}: ${consent.state}`);
+    }
+    for (const item of items) {
+      const gate = item.gate || {};
+      console.log(
+        `  ${item.kind} #${item.id}: ${gate.publishable ? "PUBLIC" : `private (${gate.reason || "live"})`}${item.caption ? ` · ${item.caption}` : ""}${item.url ? ` · ${item.url}` : ""}`,
+      );
+    }
+    if ((story.review?.nameWarnings || []).length) {
+      console.log(`  Possible real names: ${story.review.nameWarnings.join(", ")}`);
+    }
+    if (story.body) console.log(`\n${story.body}\n`);
+    return;
+  }
+  if (operation.name.startsWith("meetup.story.")) {
+    const r = data.result || {};
+    if (operation.name === "meetup.story.approve") {
+      console.log(
+        `Published story #${r.storyId} (crew #${r.crewId}): ${(r.publicMediaIds || []).length} public, ${(r.privateMediaIds || []).length} private.${r.announcementSubjectId ? ` Announcement: subject #${r.announcementSubjectId}.` : ""}${(r.failed || []).length ? ` FAILED to process: ${r.failed.map((f) => `#${f.mediaId} ${f.error}`).join("; ")}.` : ""}`,
+      );
+    } else {
+      console.log(`${operation.name === "meetup.story.unpublish" ? "Unpublished" : "Sent back"} story #${r.storyId} (crew #${r.crewId}).`);
+    }
+    return;
+  }
   if (operation.name === "meetup.list") {
     const crews = Array.isArray(data.crews) ? data.crews : [];
     console.log(`${crews.length} meetup crew(s) (${data.filter || "review"}):`);

package/lib/commands.js

@@ -2355,6 +2355,7 @@ export function parseArgs(args) {
   const raw = {};
   const positional = [];
   const booleanFlags = new Set([
+    "noAnnounce",
     "noLeaseKeeper",
     "noOpen",
     "open",
@@ -2596,6 +2597,7 @@ export function parseArgs(args) {
     adminUnviewed: Boolean(raw.unviewed),
     adminViewed: Boolean(raw.viewed),
     adminIdentity: raw.identity ? String(raw.identity) : "",
+    adminVia: raw.via ? String(raw.via) : "",
     adminScope: raw.scope ? String(raw.scope) : "",
     commentMode: raw.commentMode ? String(raw.commentMode) : "",
     runKey: raw.runKey ? String(raw.runKey) : "",
@@ -2606,6 +2608,7 @@ export function parseArgs(args) {
     storageSize: raw.size ? String(raw.size) : "",
     adminAttended: raw.attended ? String(raw.attended) : "",
     adminConfirm: raw.confirm === undefined ? "" : String(raw.confirm),
+    adminNoAnnounce: Boolean(raw.noAnnounce),
     adminContextLimit: raw.limit === undefined ? 20 : Number(raw.limit),
     adminRun: raw.run ? String(raw.run) : "",
     adminTarget: raw.target ? String(raw.target) : "",
@@ -3012,6 +3015,7 @@ export function printHelp() {
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
   lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]
   lumine admin meetup list [--status review|active|completed|all] | show <crewId> | approve-plan <crewId> [--note <text>] | send-back <crewId> --note <text> | approve <crewId> --attended <userId,userId,...> [--note <text>] | slot <crewId> --confirm <slotIndex> | resend-email <crewId>   (Bridge Builder meetup quest)
+  lumine admin meetup story list | show <crewId> | approve <crewId> [--note <text>] [--no-announce] | send-back <crewId> --note <text> | unpublish <crewId> --note <text>   (Bridge Builder story pages: publishes only what every tagged member's parent allowed)
   lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
   lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] [--json]
   lumine admin chat-reports show <report-id> [--json]   (reported message snapshot + surrounding context)
@@ -3059,6 +3063,9 @@ export function printHelp() {
   lumine admin comment draft <target> [--type subject|comment|build|aiStory|dailyReflection] [--file <comment.md>] [--review-receipt <review.json>|--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment reply comment:<id> [--file <reply.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment post --draft-id <id> [--json]
+  lumine admin comment session start --identity zero|ciel --target <subject:ID|comment:ID|build:ID|aiStory:ID>[,...] [--reason <text>] [--json]
+  lumine admin comment session status|close [--json]
+    (with both a comment session and a daily run active, comment draft/reply/post/edit need --via session|run)
   lumine admin comment edit <comment-id> --file <comment.md> [--review-receipt <review.json> | --reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--json]
   lumine admin brief [--days <1..30>] [--json]
   lumine admin ai-costs monthly [--output <file.json>] [--json] (no active run required)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.98",
+  "version": "0.3.0",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/LUMINE_ADMIN.md

@@ -4171,6 +4171,74 @@ canonical review record ID before claiming success. Older APIs that still block
 Build edits must be deployed first; do not silently substitute a duplicate reply
 when Mikey requested an edit.
 
+### Standalone comment sessions
+
+Posting a few new comments or replies as Zero or Ciel does not require a full
+daily run. An approved operator names the identity and the exact targets:
+
+```bash
+lumine admin comment session start --identity ciel \
+  --target subject:123,comment:456 --reason "Mikey asked for a reply" --json
+lumine admin subject get 123 --include-comments --json
+lumine admin comment draft subject:123 --file comment.md --json
+lumine admin comment reply comment:456 --file reply.md --json
+lumine admin comment post --draft-id <id> --json
+lumine admin comment edit <commentId> --file corrected.md --json
+lumine admin comment session status --json
+lumine admin comment session close --json
+```
+
+`--target` takes a comma-separated list (extra space-separated targets after
+it also count); each is `subject:ID`, `comment:ID`, `build:ID`, `aiStory:ID` or
+`dailyReflection:ID`, at most ten. Pass them in one `--target`: a repeated
+`--target` flag keeps only its last value. The server checks every target when
+the session starts and refuses one the draft path would refuse later.
+
+What the session authorizes:
+
+- **Scopes:** only `content:read`, `comment:draft` and `comment:post`. No chat,
+  Featured, reward, recommendation, subject, newspaper or run-completion
+  command works through it; those still need a daily run.
+- **Target lock:** drafts, replies and the reads above work only on the named
+  targets. A reply target counts when it is a named `comment:ID`, or a comment
+  sitting directly in a named subject, Build, AI Story or Daily Reflection.
+  Anything else fails with `CLI_ADMIN_COMMENT_SESSION_TARGET_FORBIDDEN` and
+  the allowed list. `comment post` accepts only drafts created in the session.
+- **Edits:** `comment edit <commentId>` works under the session only for a
+  comment this session itself posted, as the same identity
+  (`CLI_ADMIN_COMMENT_SESSION_EDIT_FORBIDDEN` otherwise). The usual edit rules
+  apply unchanged, including fresh Build review evidence for a Build comment.
+  Edits do not count toward the post cap.
+- **Limits:** 30 minutes, at most five published comments
+  (`CLI_ADMIN_COMMENT_SESSION_POST_CAP`), one active session per operator.
+  `close` or the TTL ends it; start a new session for more.
+- **Same bar as a daily run:** drafting and publishing use the exact daily-run
+  draft/publish path. Build comments still require composed text, a review
+  receipt or `--reviewed-version/--reviewed-via` evidence of the current
+  published version, and `--review-context`; context and persona revisions
+  are checked at publish time as usual.
+- **Identity:** the operator must be an approved delegated administrator, and
+  the session posts only as the identity named at start (`--identity auto` is
+  not accepted). It does not change the Bangkok calendar assignment or the
+  identity preference.
+
+A comment session and a daily run can be active together, but every request
+carries exactly one authority. The session never claims the daily-run slot.
+
+- When only one of them is active, the CLI uses it.
+- When both are active, `comment draft`, `comment reply`, `comment post` and
+  `comment edit` refuse to run until you choose with `--via session` or
+  `--via run`. Target reads (`subject get`, `post get`, `comments get`, their
+  comment lists) default to the daily run and take `--via session` to read
+  through the session instead.
+- The API refuses a request that names a comment session together with a
+  daily run or correction session (`CLI_ADMIN_AMBIGUOUS_AUTHORITY`); a session
+  request outside the session is refused, never handed to the run.
+- A draft records the authority that created it, and only that authority can
+  publish it (`CLI_ADMIN_DRAFT_AUTHORITY_MISMATCH`).
+- A correction session still takes precedence for its one comment; `--via` is
+  refused while it is active for that comment.
+
 **Editing the bot's own comments.** `comment edit <commentId> --file
 <comment.md>` replaces the text of a comment the acting bot itself authored —
 for correcting a factual error, an unfulfillable claim, or outdated guidance