@rubytech/create-maxy-code 0.1.174 → 0.1.177

package/payload/premium-plugins/writer-craft/mcp/src/cli/ingest-session-text.ts

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * CLI wrapper for voice-ingest-session-text.
+ *
+ * Invoked by the SessionEnd hook after each admin PTY session:
+ *   node dist/cli/ingest-session-text.js <transcript_path>
+ *
+ * All other parameters are read from environment variables inherited from
+ * the PTY session (which inherits from the session manager's systemd unit):
+ *
+ *   ACCOUNT_ID    — operator's account identifier
+ *   USER_ID       — operator's userId (= adminUserId)
+ *   SESSION_ID    — session identifier (parsed by hook from stdin)
+ *   NEO4J_URI     — neo4j bolt URI
+ *   NEO4J_USER    — neo4j username
+ *   NEO4J_PASSWORD — neo4j password
+ *
+ * Exit codes:
+ *   0 — success (includes no-new-turns case)
+ *   1 — error (missing required env, JSONL not found, DB error)
+ *
+ * stdout: one-line result summary ("turns=N skipped=M") for the hook to
+ * capture and forward to the log-ingest endpoint.
+ * stderr: detailed diagnostics (tool log lines).
+ */
+import { voiceIngestSessionText } from "../tools/voice-ingest-session-text.js";
+import { closeDriver } from "../lib/neo4j.js";
+
+const transcriptPath = process.argv[2];
+if (!transcriptPath) {
+  process.stderr.write("[ingest-session-text] error: transcript path required as argv[2]\n");
+  process.exit(1);
+}
+
+const accountId = process.env.ACCOUNT_ID ?? "";
+const userId = process.env.USER_ID ?? "";
+const sessionId = process.env.SESSION_ID ?? undefined;
+
+if (!accountId || !userId) {
+  process.stderr.write(
+    `[ingest-session-text] error: ACCOUNT_ID and USER_ID must be set in env (accountId=${accountId || "empty"} userId=${userId || "empty"})\n`,
+  );
+  process.exit(1);
+}
+
+try {
+  const result = await voiceIngestSessionText({
+    sessionJsonlPath: transcriptPath,
+    accountId,
+    userId,
+    sessionId,
+  });
+  // Emit one-line summary to stdout for the hook to capture.
+  process.stdout.write(
+    `turns=${result.ingestedCount} skipped=${result.skippedCount} sessionId=${result.sessionId ?? "unknown"}\n`,
+  );
+  process.exit(0);
+} catch (err) {
+  process.stderr.write(
+    `[ingest-session-text] error: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  process.exit(1);
+} finally {
+  await closeDriver();
+}

package/payload/premium-plugins/writer-craft/mcp/src/index.ts

@@ -8,6 +8,8 @@ import { voiceTagContent, AUTHORSHIP_MODES, type AuthorshipMode } from "./tools/
 import { voiceDistilProfile } from "./tools/voice-distil-profile.js";
 import { voiceRetrieveConditioning } from "./tools/voice-retrieve-conditioning.js";
 import { voiceRecordFeedback } from "./tools/voice-record-feedback.js";
+import { voiceIngestSessionText } from "./tools/voice-ingest-session-text.js";
+import { FORMAT_VALUES } from "./lib/voice-corpus.js";
 import { closeDriver } from "./lib/neo4j.js";
 
 const server = new McpServer({
@@ -46,9 +48,14 @@ function resolveUserId(): string | null {
   return userIdEnv;
 }
 
+// Format enum schema — shared across tools that accept VoiceFormat.
+const zFormat = z.enum([...FORMAT_VALUES] as [string, ...string[]]).describe(
+  "Writing format: text | email | social-post | article | marketing-copy | note. One :VoiceProfile per (accountId, userId, format).",
+);
+
 server.tool(
   "voice-tag-content",
-  "Stamp authorshipMode on one or many content nodes (:KnowledgeDocument | :Message | :SocialPost) the operator owns. Email threads live as :KnowledgeDocument {source:'email'} since Task 321. Valid modes: human-only, human-led-agent-assisted, agent-led-human-reviewed, agent-only, unknown.",
+  "Stamp authorshipMode (and optionally format) on one or many content nodes (:KnowledgeDocument | :Message | :SocialPost) the operator owns. Email threads live as :KnowledgeDocument {source:'email'} since Task 321. Valid modes: human-only, human-led-agent-assisted, agent-led-human-reviewed, agent-only, unknown. Valid formats: text, email, social-post, article, marketing-copy, note. When format is omitted, it is derived per-node from labels and source property.",
   {
     nodeIds: z.array(z.string()).min(1).describe("Element IDs of nodes to tag"),
     mode: z
@@ -60,20 +67,24 @@ server.tool(
         "unknown",
       ])
       .describe("Authorship mode to apply"),
+    format: zFormat.optional().describe(
+      "Writing format. When omitted, derived from each node's labels and source property.",
+    ),
   },
-  async ({ nodeIds, mode }) => {
+  async ({ nodeIds, mode, format }) => {
     if (!accountId) return refuseNoAccount("voice-tag-content");
     try {
       const result = await voiceTagContent({
         nodeIds,
         mode: mode as AuthorshipMode,
         accountId,
+        format: format as import("./lib/voice-corpus.js").VoiceFormat | undefined,
       });
       return {
         content: [
           {
             type: "text" as const,
-            text: `voice-tag: mode=${mode} updated=${result.updated} skipped=${result.skipped}`,
+            text: `voice-tag: mode=${mode} format=${format ?? "derived"} updated=${result.updated} skipped=${result.skipped}`,
           },
         ],
       };
@@ -93,7 +104,7 @@ server.tool(
 
 server.tool(
   "voice-distil-profile",
-  "Two-mode tool (Task 424). mode='sample' (default) walks the operator's human-only corpus, returns the exemplars + recent operator-edit intents for the agent to read. mode='write' persists the YAML style card the agent composed from the sample-mode response. Cadence-guarded: returns skip in 'write' mode without writing if corpus didn't grow ≥20% AND <30 days passed (pass force=true to override).",
+  "Two-mode tool (Task 424). mode='sample' (default) walks the operator's per-format human-only corpus, returns exemplars + recent edit intents for the agent to read. mode='write' persists the YAML style card the agent composed. Cadence-guarded: skips in 'write' mode without writing if corpus didn't grow ≥20% AND <30 days passed (pass force=true to override). When format is omitted, enumerates all formats in the corpus and distils each.",
   {
     userId: z
       .string()
@@ -101,6 +112,9 @@ server.tool(
       .describe(
         "Operator AdminUser identifier. Defaults to ADMIN_USER_ID env from spawn context.",
       ),
+    format: zFormat.optional().describe(
+      "Writing format to distil. When omitted, enumerates corpus formats and distils each that fires the cadence guard.",
+    ),
     force: z
       .boolean()
       .optional()
@@ -114,7 +128,7 @@ server.tool(
       .optional()
       .describe("Required for mode='write'. The YAML style card the agent composed from the sample-mode exemplars + feedback intents."),
   },
-  async ({ userId, force, mode, styleCardYaml }) => {
+  async ({ userId, format, force, mode, styleCardYaml }) => {
     if (!accountId) return refuseNoAccount("voice-distil-profile");
     const resolvedUserId = userId ?? resolveUserId();
     if (!resolvedUserId) {
@@ -133,15 +147,31 @@ server.tool(
       const result = await voiceDistilProfile({
         accountId,
         userId: resolvedUserId,
+        format: format as import("./lib/voice-corpus.js").VoiceFormat | undefined,
         force: force === true,
         mode,
         styleCardYaml,
       });
-      const summary = result.skipped
-        ? (result.exemplars
-            ? `voice-distil sample: corpusSize=${result.corpusSize} exemplars=${result.exemplars.length} feedbackEntries=${result.feedbackEntries}\n${JSON.stringify({ exemplars: result.exemplars, feedbackIntents: result.feedbackIntents }, null, 2)}`
-            : `voice-distil: skipped reason=${result.skipReason} corpusSize=${result.corpusSize}`)
-        : `voice-distil: ok profileId=${result.profileId} corpusSize=${result.corpusSize} feedbackEntries=${result.feedbackEntries} generatedAt=${result.generatedAt}`;
+
+      // Summarise single-format or multi-format result.
+      const summariseOne = (r: import("./tools/voice-distil-profile.js").VoiceDistilProfileResult, fmt?: string): string => {
+        const tag = fmt ? ` format=${fmt}` : "";
+        if (r.skipped && r.exemplars) {
+          return `voice-distil sample${tag}: corpusSize=${r.corpusSize} exemplars=${r.exemplars.length} feedbackEntries=${r.feedbackEntries}\n${JSON.stringify({ exemplars: r.exemplars, feedbackIntents: r.feedbackIntents }, null, 2)}`;
+        }
+        if (r.skipped) {
+          return `voice-distil${tag}: skipped reason=${r.skipReason} corpusSize=${r.corpusSize}`;
+        }
+        return `voice-distil${tag}: ok profileId=${r.profileId} corpusSize=${r.corpusSize} feedbackEntries=${r.feedbackEntries} generatedAt=${r.generatedAt}`;
+      };
+
+      let summary: string;
+      if (Array.isArray(result)) {
+        summary = result.map((r, i) => summariseOne(r)).join("\n---\n");
+      } else {
+        summary = summariseOne(result, format);
+      }
+
       return { content: [{ type: "text" as const, text: summary }] };
     } catch (err) {
       return {
@@ -159,23 +189,25 @@ server.tool(
 
 server.tool(
   "voice-retrieve-conditioning",
-  "Return the operator's style card and K voice-matched exemplars for a drafting brief. K=5 short-form, K=15 long-form. Token-budget bounded. Returns empty {styleCard:null,exemplars:[]} when no profile exists.",
+  "Return the operator's per-format style card and K voice-matched exemplars for a drafting brief. K=5 short-form (length='short'), K=15 long-form (length='long'). Token-budget bounded. format is required (the writing type: text|email|social-post|article|marketing-copy|note). Returns empty {styleCard:null,exemplars:[]} when no profile exists.",
   {
     userId: z
       .string()
       .optional()
       .describe("Operator AdminUser identifier. Defaults to ADMIN_USER_ID env."),
+    format: zFormat.describe("Writing format for corpus and profile scoping."),
     topic: z
       .string()
       .optional()
       .describe("Drafting topic keyword (filters exemplars to relevant ones)"),
-    format: z
+    length: z
       .enum(["short", "long"])
-      .describe("Short = email/post (K=5, 16k tokens); long = brochure/prospectus (K=15, 96k tokens)"),
+      .optional()
+      .describe("K-selector: short = K=5 (16k tokens, email/post); long = K=15 (96k tokens, brochure/prospectus). Defaults to short."),
     register: z.string().optional().describe("Optional register hint"),
     tokenBudget: z.number().int().positive().optional(),
   },
-  async ({ userId, topic, format, register, tokenBudget }) => {
+  async ({ userId, format, topic, length, register, tokenBudget }) => {
     if (!accountId) return refuseNoAccount("voice-retrieve-conditioning");
     const resolvedUserId = userId ?? resolveUserId();
     if (!resolvedUserId) {
@@ -192,7 +224,12 @@ server.tool(
       const result = await voiceRetrieveConditioning({
         accountId,
         userId: resolvedUserId,
-        brief: { topic, format, register },
+        brief: {
+          format: format as import("./lib/voice-corpus.js").VoiceFormat,
+          topic,
+          length: length as "short" | "long" | undefined,
+          register,
+        },
         tokenBudget,
       });
       return {
@@ -220,9 +257,10 @@ server.tool(
 
 server.tool(
   "voice-record-feedback",
-  "Capture an operator's edit on an agent draft. Writes :VoiceEdit linked to :VoiceProfile via :FEEDBACK_FOR. The calling agent supplies `intent` (one sentence describing what the operator changed and what voice preference it reveals); Task 424 moved the diff-intent summarisation into the agent's turn.",
+  "Capture an operator's edit on an agent draft. Writes :VoiceEdit linked to the per-format :VoiceProfile via :FEEDBACK_FOR. The calling agent supplies `intent` (one sentence describing what changed and what voice preference it reveals — Task 424) and `format` (the writing format of the draft).",
   {
     userId: z.string().optional(),
+    format: zFormat.describe("Writing format of the draft being edited."),
     originalText: z.string().min(1),
     editedText: z.string().min(1),
     intent: z
@@ -232,7 +270,7 @@ server.tool(
     skill: z.string().optional().describe("Calling skill name, for provenance"),
     brief: z.string().optional().describe("Drafting brief that produced the original"),
   },
-  async ({ userId, originalText, editedText, intent, skill, brief }) => {
+  async ({ userId, format, originalText, editedText, intent, skill, brief }) => {
     if (!accountId) return refuseNoAccount("voice-record-feedback");
     const resolvedUserId = userId ?? resolveUserId();
     if (!resolvedUserId) {
@@ -250,6 +288,7 @@ server.tool(
       const result = await voiceRecordFeedback({
         accountId,
         userId: resolvedUserId,
+        format: format as import("./lib/voice-corpus.js").VoiceFormat,
         originalText,
         editedText,
         intent,
@@ -259,7 +298,7 @@ server.tool(
         content: [
           {
             type: "text" as const,
-            text: `voice-record-feedback: editId=${result.editId} intent="${result.intent}" hadProfile=${result.hadProfile}`,
+            text: `voice-record-feedback: editId=${result.editId} format=${format} intent="${result.intent}" hadProfile=${result.hadProfile}`,
           },
         ],
       };
@@ -277,6 +316,57 @@ server.tool(
   },
 );
 
+server.tool(
+  "voice-ingest-session-text",
+  "Ingest operator PTY turns from a Claude Code session JSONL as :Message {format:'text', source:'admin-pty', authorshipMode:'human-only'} corpus nodes. Deduplication via SHA256 contentHash — re-running against the same JSONL is a no-op. Triggers voice-distil-profile {format:'text'} after ingest (cadence guard decides whether distillation runs). Called automatically by the SessionEnd hook; can also be invoked manually.",
+  {
+    sessionJsonlPath: z.string().min(1).describe("Absolute path to the Claude Code session JSONL file"),
+    sessionId: z.string().optional().describe("Session ID for provenance; read from the SessionEnd envelope"),
+    userId: z.string().optional().describe("Operator AdminUser identifier. Defaults to ADMIN_USER_ID env."),
+  },
+  async ({ sessionJsonlPath, sessionId, userId }) => {
+    if (!accountId) return refuseNoAccount("voice-ingest-session-text");
+    const resolvedUserId = userId ?? resolveUserId();
+    if (!resolvedUserId) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: "voice-ingest-session-text: userId required (no ADMIN_USER_ID in spawn env).",
+          },
+        ],
+        isError: true,
+      };
+    }
+    try {
+      const result = await voiceIngestSessionText({
+        sessionJsonlPath,
+        accountId,
+        userId: resolvedUserId,
+        sessionId,
+      });
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-ingest-session-text: ingestedCount=${result.ingestedCount} skippedCount=${result.skippedCount} sessionId=${result.sessionId ?? "unknown"}`,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-ingest-session-text failed: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 

package/payload/premium-plugins/writer-craft/mcp/src/lib/voice-corpus.ts

@@ -1,11 +1,13 @@
 /**
- * Shared corpus-filter clause for the voice-mirror tools.
+ * Shared corpus-filter clauses and format helpers for the voice-mirror tools.
  *
- * Imported by `voice-distil-profile` (count + sample walks) and
- * `voice-retrieve-conditioning` (exemplar walk). The single load-bearing
- * filter — when the corpus rules change, this is the only place to edit.
+ * Imported by `voice-distil-profile` (count + sample walks),
+ * `voice-retrieve-conditioning` (exemplar walk), `voice-tag-content` (tag
+ * writes), and `voice-ingest-session-text` (SessionEnd ingest). The single
+ * load-bearing filter — when the corpus rules change, this is the only place
+ * to edit.
  *
- * Two predicates:
+ * Two predicates in VOICE_CORPUS_WHERE:
  *
  *   1. `authorshipMode IN ['human-only', 'human-led-agent-assisted']`.
  *      `human-only` is the operator's own writing verbatim;
@@ -25,7 +27,7 @@
  *      Chat captures voice in a way email rarely does — this is the
  *      single highest-leverage corpus addition for voice fidelity.
  *
- * The clause expects `$accountId` to be bound in the calling cypher
+ * The clause expects `$accountId` to be bound in the calling Cypher
  * parameters. It does not bind any other parameters.
  */
 export const VOICE_CORPUS_WHERE = `n.accountId = $accountId
@@ -52,3 +54,73 @@ export const TAGGABLE_PRIMARY_LABELS = [
   "Message",
   "SocialPost",
 ] as const;
+
+/**
+ * Closed enum of writing-format values. One `:VoiceProfile` exists per
+ * `(accountId, userId, format)`. Adding a new value is a separate task.
+ *
+ * `marketing-copy` has no auto-derivation path — operator-tagged only.
+ */
+export const FORMAT_VALUES = [
+  "text",
+  "email",
+  "social-post",
+  "article",
+  "marketing-copy",
+  "note",
+] as const;
+
+export type VoiceFormat = (typeof FORMAT_VALUES)[number];
+
+/**
+ * Returns VOICE_CORPUS_WHERE with an additional `n.format = $format`
+ * predicate appended. Requires `$format` to be bound alongside `$accountId`
+ * in the calling Cypher parameters.
+ *
+ * Format-discovery queries (which enumerate distinct formats from the
+ * corpus) use the base `VOICE_CORPUS_WHERE` directly; per-format corpus
+ * walks use this function.
+ */
+export function voiceCorpusWhereWithFormat(format: VoiceFormat): string {
+  return `${VOICE_CORPUS_WHERE}\n  AND n.format = $format`;
+}
+
+/**
+ * Derives the default writing format for a corpus node from its labels
+ * and properties. Used by ingest writers and `voice-tag-content` when the
+ * operator does not specify a format explicitly.
+ *
+ * Derivation rules (first match wins):
+ *
+ *   | Node shape                                                  | format        |
+ *   |-------------------------------------------------------------|---------------|
+ *   | :Message                                                    | 'text'        |
+ *   | :SocialPost                                                 | 'social-post' |
+ *   | :KnowledgeDocument {source:'email'}                         | 'email'       |
+ *   | :ConversationArchive {source:'email'}                        | 'email'       |
+ *   | :KnowledgeDocument (non-email), body.length > 1500          | 'article'     |
+ *   | :KnowledgeDocument (non-email), body.length ≤ 1500          | 'note'        |
+ *   | :Section (conversation-document chunk)                      | 'text'        |
+ *   | fallback                                                    | 'text'        |
+ *
+ * `marketing-copy` has no auto-derivation path.
+ */
+export function deriveFormat(
+  labels: string[],
+  source?: string | null,
+  body?: string | null,
+): VoiceFormat {
+  if (labels.includes("Message")) return "text";
+  if (labels.includes("SocialPost")) return "social-post";
+  if (
+    (labels.includes("KnowledgeDocument") || labels.includes("ConversationArchive")) &&
+    source === "email"
+  ) {
+    return "email";
+  }
+  if (labels.includes("KnowledgeDocument")) {
+    return (body?.length ?? 0) > 1500 ? "article" : "note";
+  }
+  // :Section (conversation-document chunk) and any other label → text.
+  return "text";
+}