@stage5/lumine 0.2.99 → 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",
@@ -3361,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,

package/lib/commands.js

@@ -2597,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) : "",
@@ -3062,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.99",
+  "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