@rubytech/create-maxy 1.0.708 → 1.0.710

package/payload/platform/lib/oauth-llm/src/index.ts

@@ -0,0 +1,526 @@
+/**
+ * OAuth-bearer LLM calls for admin-side classifiers (Task 740).
+ *
+ * Every admin-side classifier (memory-classify, memory-rank, commitment,
+ * adherence, inbound-gateway, query classifier, summarisation, email
+ * screening) uses Claude Code OAuth credentials — never the Anthropic
+ * API key. The API-key path is reserved for the public agent.
+ *
+ * Mechanism: read the access token from ~/.claude/.credentials.json,
+ * refresh it via the standard refresh-token grant if expired, then call
+ * api.anthropic.com with `Authorization: Bearer <token>` and the
+ * `anthropic-beta: oauth-2025-04-20` header. Billed against the operator's
+ * Claude Code subscription, not the API-key key. Refresh uses a
+ * module-level mutex so concurrent classifier calls during expiry don't
+ * race and invalidate each other's tokens (Anthropic rotates both tokens
+ * on refresh).
+ *
+ * Implementation note: this lib uses raw fetch() rather than the
+ * @anthropic-ai/sdk package to keep the lib dependency-free — every
+ * consumer already has its own SDK copy for other purposes, but the
+ * shared lib would create a circular package dependency. The Messages
+ * API surface we use (model + system + one user message + max_tokens)
+ * is small and stable.
+ *
+ * Failure modes are surfaced as a structured `Result` so callers can
+ * pattern-match without parsing error strings. The skill / agent layer
+ * is responsible for translating `fallback` results into operator-visible
+ * blocker messages (loud failure doctrine — Task 540, 740).
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+
+// ---------------------------------------------------------------------------
+// Constants — token endpoint, client id, beta header, file path.
+// All four are pinned values that match the Claude Code CLI's own usage.
+// ---------------------------------------------------------------------------
+
+const CREDENTIALS_FILE = resolve(homedir(), ".claude", ".credentials.json");
+const TOKEN_ENDPOINT = "https://platform.claude.com/v1/oauth/token";
+const ANTHROPIC_MESSAGES_ENDPOINT = "https://api.anthropic.com/v1/messages";
+const ANTHROPIC_VERSION = "2023-06-01";
+const CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+const OAUTH_BETA_HEADER = "oauth-2025-04-20";
+
+/** Refresh proactively when the token expires within this window. */
+const EXPIRING_THRESHOLD_MS = 5 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface ClaudeCredentials {
+  accessToken: string;
+  refreshToken: string | null;
+  expiresAt: number;
+}
+
+/** Anthropic tool definition — structural-output enforcement via function calling. */
+export interface OauthLlmTool {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+}
+
+export interface CallOauthLlmParams {
+  /** Anthropic model id (e.g. claude-haiku-4-5). */
+  model: string;
+  /** System prompt — the classifier instructions. */
+  system: string;
+  /** User message — the input to classify / rank / etc. */
+  userMessage: string;
+  /** Max output tokens. Default 4096. */
+  maxTokens?: number;
+  /** Hard timeout in ms for the model call. Default 60_000. */
+  timeoutMs?: number;
+  /**
+   * Optional tools for structured output. When provided with a forced
+   * `toolChoiceName`, the model returns a `tool_use` block whose `input` is
+   * a structured object matching the tool's `input_schema` — strictly typed
+   * JSON without the parsing brittleness of free-form text output.
+   */
+  tools?: OauthLlmTool[];
+  /** Force the model to call this tool. Required when `tools` is provided. */
+  toolChoiceName?: string;
+}
+
+/** Result when the call did not declare any tool — only text or fallback. */
+export type CallOauthLlmTextResult =
+  | { kind: "ok"; text: string }
+  | CallOauthLlmFallback;
+
+/** Result when the call forced a tool — only the tool input or fallback. */
+export type CallOauthLlmToolResult =
+  | { kind: "ok-tool"; toolName: string; input: Record<string, unknown> }
+  | CallOauthLlmFallback;
+
+/** Discriminated union of every possible result. Returned by the no-overload form. */
+export type CallOauthLlmResult = CallOauthLlmTextResult | CallOauthLlmToolResult;
+
+export interface CallOauthLlmFallback {
+  kind: "fallback";
+  /** Human-readable single-line reason (for operator-visible blocker). */
+  reason: string;
+  /** Stable classifier — callers can pattern-match for retry/abort policy. */
+  cause:
+    | "missing-creds"
+    | "dead-token"
+    | "refresh-failed"
+    | "auth-error"
+    | "rate-limit"
+    | "server-error"
+    | "network-error"
+    | "timeout"
+    | "empty-response"
+    | "malformed-response"
+    | "unexpected";
+}
+
+// ---------------------------------------------------------------------------
+// Credential reading + refresh — minimal duplicate of platform/ui claude-auth.
+// We duplicate (not import) so this lib stays self-contained and importable
+// from MCP plugins via dist/. The duplicated logic is small and the auth
+// mechanism is pinned by Anthropic — divergence risk is low.
+// ---------------------------------------------------------------------------
+
+function readCredentials(): ClaudeCredentials | null {
+  let raw: string;
+  try {
+    raw = readFileSync(CREDENTIALS_FILE, "utf-8");
+  } catch {
+    return null;
+  }
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+
+  const oauth = data.claudeAiOauth as Record<string, unknown> | undefined;
+  if (!oauth || typeof oauth !== "object") return null;
+
+  const accessToken = oauth.accessToken;
+  const refreshToken = oauth.refreshToken;
+  const expiresAt = oauth.expiresAt;
+
+  if (typeof accessToken !== "string" || !accessToken) return null;
+  if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt) || expiresAt <= 0) {
+    return null;
+  }
+
+  return {
+    accessToken,
+    refreshToken:
+      typeof refreshToken === "string" && refreshToken ? refreshToken : null,
+    expiresAt,
+  };
+}
+
+function writeCredentials(tokens: {
+  accessToken: string;
+  refreshToken: string | null;
+  expiresIn: number | undefined;
+}): number {
+  const newExpiresAt =
+    typeof tokens.expiresIn === "number" && tokens.expiresIn > 0
+      ? Date.now() + tokens.expiresIn * 1000
+      : Date.now() + 3600 * 1000;
+
+  let fileData: Record<string, unknown> = {};
+  try {
+    fileData = JSON.parse(readFileSync(CREDENTIALS_FILE, "utf-8")) as Record<
+      string,
+      unknown
+    >;
+  } catch {
+    // start fresh
+  }
+
+  const existing = fileData.claudeAiOauth as Record<string, unknown> | undefined;
+  fileData.claudeAiOauth = {
+    ...existing,
+    accessToken: tokens.accessToken,
+    ...(tokens.refreshToken != null ? { refreshToken: tokens.refreshToken } : {}),
+    expiresAt: newExpiresAt,
+  };
+
+  writeFileSync(CREDENTIALS_FILE, JSON.stringify(fileData, null, 2), "utf-8");
+  return newExpiresAt;
+}
+
+// Module-level mutex serialises refresh calls. Anthropic rotates both
+// tokens on refresh; concurrent unsynchronised refreshes invalidate
+// each other.
+let refreshLock: Promise<ClaudeCredentials | null> | null = null;
+
+async function refreshAccessToken(
+  current: ClaudeCredentials,
+): Promise<ClaudeCredentials | null> {
+  if (refreshLock) return refreshLock;
+
+  refreshLock = (async () => {
+    // Re-read inside the lock — another caller may have refreshed already.
+    const fresh = readCredentials();
+    if (fresh && fresh.expiresAt - Date.now() > EXPIRING_THRESHOLD_MS) {
+      return fresh;
+    }
+    if (!current.refreshToken) {
+      return null;
+    }
+
+    let res: Response;
+    try {
+      res = await fetch(TOKEN_ENDPOINT, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "refresh_token",
+          refresh_token: current.refreshToken,
+          client_id: CLIENT_ID,
+        }),
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`[oauth-llm] refresh network error: ${msg}`);
+      return null;
+    }
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      console.error(
+        `[oauth-llm] refresh failed status=${res.status} body=${body.slice(0, 200)}`,
+      );
+      return null;
+    }
+
+    let tokenData: Record<string, unknown>;
+    try {
+      tokenData = (await res.json()) as Record<string, unknown>;
+    } catch {
+      console.error("[oauth-llm] refresh returned malformed JSON");
+      return null;
+    }
+
+    const newAccessToken = tokenData.access_token;
+    const newRefreshToken = tokenData.refresh_token;
+    const expiresIn = tokenData.expires_in;
+
+    if (typeof newAccessToken !== "string" || !newAccessToken) {
+      console.error("[oauth-llm] refresh response missing access_token");
+      return null;
+    }
+
+    const newExpiresAt = writeCredentials({
+      accessToken: newAccessToken,
+      refreshToken:
+        typeof newRefreshToken === "string" && newRefreshToken
+          ? newRefreshToken
+          : current.refreshToken,
+      expiresIn: typeof expiresIn === "number" && expiresIn > 0 ? expiresIn : undefined,
+    });
+
+    console.error(
+      `[oauth-llm] refresh ok expiresAt=${new Date(newExpiresAt).toISOString()}`,
+    );
+
+    return {
+      accessToken: newAccessToken,
+      refreshToken:
+        typeof newRefreshToken === "string" && newRefreshToken
+          ? newRefreshToken
+          : current.refreshToken,
+      expiresAt: newExpiresAt,
+    };
+  })();
+
+  try {
+    return await refreshLock;
+  } finally {
+    refreshLock = null;
+  }
+}
+
+/**
+ * Read credentials and proactively refresh if approaching expiry.
+ * Returns null when the credentials are missing or unrecoverable
+ * (operator must re-authenticate via Claude Code login).
+ */
+async function ensureValidToken(): Promise<ClaudeCredentials | null> {
+  const creds = readCredentials();
+  if (!creds) return null;
+
+  const remaining = creds.expiresAt - Date.now();
+  if (remaining > EXPIRING_THRESHOLD_MS) return creds;
+  if (remaining > 0 && !creds.refreshToken) return creds; // valid but no way to renew
+  if (remaining <= 0 && !creds.refreshToken) return null; // dead
+
+  return refreshAccessToken(creds);
+}
+
+// ---------------------------------------------------------------------------
+// First-call beta-header diagnostic — emitted once per process so server.log
+// makes the OAuth path visible without flooding on every classifier call.
+// ---------------------------------------------------------------------------
+
+let betaHeaderLogged = false;
+
+function logBetaHeaderOnce(): void {
+  if (betaHeaderLogged) return;
+  betaHeaderLogged = true;
+  console.error(`[oauth-llm] beta-header=${OAUTH_BETA_HEADER}`);
+}
+
+// ---------------------------------------------------------------------------
+// Anthropic Messages API response shape — narrow subset we depend on.
+// ---------------------------------------------------------------------------
+
+interface AnthropicMessagesResponse {
+  content?: Array<
+    | { type: "text"; text?: string }
+    | { type: "tool_use"; name?: string; input?: Record<string, unknown> }
+    | { type: string }
+  >;
+  error?: { type?: string; message?: string };
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Call an Anthropic model via OAuth bearer auth.
+ *
+ * Returns:
+ *   { kind: "ok", text }                   — model's text response
+ *   { kind: "ok-tool", toolName, input }   — when `tools` + `toolChoiceName` provided
+ *   { kind: "fallback", reason, cause }    — caller decides whether to abort
+ *
+ * The caller is responsible for translating fallback results into
+ * operator-visible blocker messages — this wrapper never silently
+ * substitutes a degraded response.
+ *
+ * Overloads narrow the return type by call shape: text-only callers (no
+ * `tools`) statically rule out `ok-tool`; tool callers statically rule out
+ * `ok`. Mixed callers get the full union.
+ */
+export function callOauthLlm(
+  params: Omit<CallOauthLlmParams, "tools" | "toolChoiceName">,
+): Promise<CallOauthLlmTextResult>;
+export function callOauthLlm(
+  params: CallOauthLlmParams & { tools: OauthLlmTool[]; toolChoiceName: string },
+): Promise<CallOauthLlmToolResult>;
+export function callOauthLlm(
+  params: CallOauthLlmParams,
+): Promise<CallOauthLlmResult>;
+export async function callOauthLlm(
+  params: CallOauthLlmParams,
+): Promise<CallOauthLlmResult> {
+  const {
+    model,
+    system,
+    userMessage,
+    maxTokens = 4096,
+    timeoutMs = 60_000,
+    tools,
+    toolChoiceName,
+  } = params;
+
+  if (tools && tools.length > 0 && !toolChoiceName) {
+    return {
+      kind: "fallback",
+      cause: "unexpected",
+      reason: "callOauthLlm: `tools` provided without `toolChoiceName`. Forced tool selection is required.",
+    };
+  }
+
+  logBetaHeaderOnce();
+
+  const creds = await ensureValidToken();
+  if (!creds) {
+    return {
+      kind: "fallback",
+      cause: "missing-creds",
+      reason:
+        "Claude Code OAuth credentials missing or expired with no refresh token available — operator must re-authenticate.",
+    };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let res: Response;
+  try {
+    res = await fetch(ANTHROPIC_MESSAGES_ENDPOINT, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "anthropic-version": ANTHROPIC_VERSION,
+        "anthropic-beta": OAUTH_BETA_HEADER,
+        Authorization: `Bearer ${creds.accessToken}`,
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: maxTokens,
+        system,
+        messages: [{ role: "user", content: userMessage }],
+        ...(tools && tools.length > 0 ? { tools } : {}),
+        ...(toolChoiceName
+          ? { tool_choice: { type: "tool", name: toolChoiceName } }
+          : {}),
+      }),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    clearTimeout(timer);
+    const msg = err instanceof Error ? err.message : String(err);
+    if (controller.signal.aborted) {
+      return {
+        kind: "fallback",
+        cause: "timeout",
+        reason: `Model call timed out after ${timeoutMs}ms.`,
+      };
+    }
+    return {
+      kind: "fallback",
+      cause: "network-error",
+      reason: `Network error reaching Anthropic: ${msg}`,
+    };
+  }
+  clearTimeout(timer);
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    if (res.status === 401 || res.status === 403) {
+      return {
+        kind: "fallback",
+        cause: "auth-error",
+        reason: `OAuth bearer rejected (status=${res.status}) — token may be revoked or beta header rejected. body=${body.slice(0, 200)}`,
+      };
+    }
+    if (res.status === 429) {
+      return {
+        kind: "fallback",
+        cause: "rate-limit",
+        reason: `Anthropic rate limit hit (status=429): ${body.slice(0, 200)}`,
+      };
+    }
+    if (res.status >= 500) {
+      return {
+        kind: "fallback",
+        cause: "server-error",
+        reason: `Anthropic server error (status=${res.status}): ${body.slice(0, 200)}`,
+      };
+    }
+    return {
+      kind: "fallback",
+      cause: "unexpected",
+      reason: `Anthropic returned status=${res.status}: ${body.slice(0, 200)}`,
+    };
+  }
+
+  let payload: AnthropicMessagesResponse;
+  try {
+    payload = (await res.json()) as AnthropicMessagesResponse;
+  } catch {
+    return {
+      kind: "fallback",
+      cause: "malformed-response",
+      reason: "Anthropic returned malformed JSON.",
+    };
+  }
+
+  if (payload.error) {
+    return {
+      kind: "fallback",
+      cause: "unexpected",
+      reason: `Anthropic API error: ${payload.error.type ?? "unknown"} ${payload.error.message ?? ""}`,
+    };
+  }
+
+  // When the caller forced a tool, prefer the tool_use block — its input
+  // is the structured output the caller wants.
+  if (toolChoiceName) {
+    const toolBlock = payload.content?.find(
+      (block): block is { type: "tool_use"; name?: string; input?: Record<string, unknown> } =>
+        block.type === "tool_use",
+    );
+    if (!toolBlock || !toolBlock.input || typeof toolBlock.input !== "object") {
+      return {
+        kind: "fallback",
+        cause: "empty-response",
+        reason: "Model returned no tool_use block despite forced tool selection.",
+      };
+    }
+    return {
+      kind: "ok-tool",
+      toolName: toolBlock.name ?? toolChoiceName,
+      input: toolBlock.input,
+    };
+  }
+
+  const textBlock = payload.content?.find(
+    (block): block is { type: "text"; text: string } => {
+      if (block.type !== "text") return false;
+      const candidate = (block as { text?: unknown }).text;
+      return typeof candidate === "string" && candidate.trim().length > 0;
+    },
+  );
+  if (!textBlock) {
+    return {
+      kind: "fallback",
+      cause: "empty-response",
+      reason: "Model returned no text content.",
+    };
+  }
+  return { kind: "ok", text: textBlock.text };
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports for callers that want to compose their own auth flow.
+// ---------------------------------------------------------------------------
+
+export { OAUTH_BETA_HEADER };

package/payload/platform/lib/oauth-llm/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/payload/platform/neo4j/schema.cypher

@@ -201,15 +201,20 @@ OPTIONS {
 };
 
 // ----------------------------------------------------------
-// KnowledgeDocument / Section / Chunk — hierarchical document ingestion
-// PRD §7: three-level hierarchy with LLM-generated summaries
+// KnowledgeDocument / Section — single-Section document ingestion (Task 740,
+// replacing the Task 737 three-level KnowledgeDocument/Section/Chunk model).
 //
-// KnowledgeDocument -[HAS_SECTION]-> Section -[HAS_CHUNK]-> Chunk
-// KnowledgeDocument -[REFERENCES]-> (any entity node)
+// KnowledgeDocument -[HAS_SECTION]-> Section
+// Section          -[NEXT]-> Section          (reading-order chain)
+// KnowledgeDocument -[PARTY]-> (Person|Organization)   (contracts only)
+// KnowledgeDocument -[REFERENCES]-> (any entity)        (legacy; no new writes)
 //
-// Summaries are embedded (not raw text). Raw chunk content is stored
-// on Chunk.content for retrieval. Full-text BM25 index spans all three
-// levels for hybrid search (0.7 vector + 0.3 BM25).
+// Every classified section is one Section node. Recognised kinds carry a
+// secondary label (Section:Position, Section:Education, Section:Chapter,
+// Section:Parties, Section:Other, etc.) — anchor edges from the document
+// subject (UserProfile/LocalBusiness) point at the multi-labeled node
+// directly. The :Chunk overflow level is gone; sections store their body
+// inline. Identifying property remains attachmentId on KnowledgeDocument.
 // ----------------------------------------------------------
 
 CREATE CONSTRAINT knowledge_doc_id_unique IF NOT EXISTS
@@ -241,6 +246,9 @@ OPTIONS {
   }
 };
 
+// Pre-Task 740 :Chunk vector index — kept for backwards compatibility with
+// Sections written before the writer rewrite. New ingests do not produce
+// :Chunk nodes; the index becomes inert once landfill is purged.
 CREATE VECTOR INDEX chunk_embedding IF NOT EXISTS
 FOR (c:Chunk) ON (c.embedding)
 OPTIONS {
@@ -250,12 +258,30 @@ OPTIONS {
   }
 };
 
-// Full-text BM25 index for hybrid keyword search across all document levels.
-// Indexes summaries (KnowledgeDocument.summary, Section.summary) and raw
-// chunk content (Chunk.content) for keyword matching alongside vector search.
+// Full-text BM25 index for hybrid keyword search across document levels.
+// Post-Task 740: sections carry their body inline so the index covers
+// KnowledgeDocument.summary, Section.summary, Section.body, and the legacy
+// Chunk.content for any Chunks still present from pre-740 ingests.
 CREATE FULLTEXT INDEX knowledge_fulltext IF NOT EXISTS
 FOR (k:KnowledgeDocument|Section|Chunk)
-ON EACH [k.summary, k.content];
+ON EACH [k.summary, k.content, k.body];
+
+// Project node (Task 740) — a standalone creative-output node distinct from
+// :Section. Anchored via (:UserProfile)-[:CREATED]->(:Project), with optional
+// (:Project)-[:UNDER]->(:Organization) when the project was done at an org.
+// Written when a CV section classifies as `Project`.
+
+CREATE INDEX project_account IF NOT EXISTS
+FOR (p:Project) ON (p.accountId);
+
+CREATE VECTOR INDEX project_embedding IF NOT EXISTS
+FOR (p:Project) ON (p.embedding)
+OPTIONS {
+  indexConfig: {
+    `vector.dimensions`: 768,
+    `vector.similarity_function`: 'cosine'
+  }
+};
 
 // ----------------------------------------------------------
 // Position node — a role held by a UserProfile at an Organization.

package/payload/platform/package.json

@@ -6,8 +6,8 @@
     "plugins/*/mcp"
   ],
   "scripts": {
-    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json",
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/anthropic-key/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
     "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",

package/payload/platform/plugins/docs/references/plugins-guide.md

@@ -115,10 +115,18 @@ After this, every `console.error("[your-tool] ...")` from any tool in the plugin
 
 **Main-subprocess stderr (Task 535).** The same teeing pattern applies to the main Claude Code subprocess's stderr — every line lands in the per-conversation stream log as `[subproc-stderr] …`, with lifecycle markers `[subproc-stderr-tee-attached] pid=…` and `[subproc-stderr-tee-detached] pid=… bytes=N lines=N`. A `bytes=0 lines=0` detach means the tee was attached but the subprocess emitted nothing on stderr — which is the normal state today, because the Claude Code CLI is a bundled Bun runtime binary that does not honour Node's `NODE_DEBUG` env var. The platform records this explicitly with one line per spawn: `[subproc-debug-unavailable] reason=bundled-bun-binary-ignores-node-debug pid=… cli=claude`. A reader who finds a `[spawn]` without these markers should treat that as a regression of the tee infrastructure, not as silence.
 
-## Failure-path observability contract (Task 560)
+## Failure-path observability contract (Task 560 + Task 743)
 
-The `initStderrTee` wrapper writes to the per-conversation stream log and per-server raw file via `createWriteStream` — async, buffered. Any diagnostic `console.error(…)` followed by an immediate `process.exit(…)` is lost: the event loop never drains the WriteStream before the process terminates. Plugins that call `process.exit()` during module load (rare — `graph-mcp` is the only in-tree example today; it spawns a child at boot to proxy upstream stdio) MUST use `fs.appendFileSync` at every exit path to guarantee the cause lands in both log destinations before exit. Lines should follow the `[mcp:<name>] [<plugin-prefix>] <cause>` format so existing `grep '[mcp:<name>]'` investigator paths work. Each destination must be wrapped in its own try/catch — an unwritable log must not mask the primary failure.
+The `initStderrTee` wrapper writes to the per-conversation stream log and per-server raw file via `createWriteStream` — async, buffered. Any diagnostic `console.error(…)` followed by an immediate `process.exit(…)` is lost: the event loop never drains the WriteStream before the process terminates. Same race for any synchronous module-load throw: Node's uncaught-exception handler writes the stack to raw fd 2 and exits before the patched async stream flushes. The platform's `[mcp-init-error] tail="(no stderr file)"` line — operationally useless — is the public symptom of this race.
 
-A second observability layer closes the same gap from the platform side: when `claude-agent.ts` observes an `init` event with any MCP server reporting `status:"failed"`, it reads the last 512 bytes of `${LOG_DIR}/mcp-<name>-stderr-<date>.log` and emits `[mcp-init-error] server=<name> tail=<quoted>` into the stream log. Absent file → `tail="(no stderr file)"`; empty file → `tail="(empty)"`. This works for every plugin regardless of whether it adopted the sync-write discipline — the tail of whatever landed in the raw stderr file (from whichever destination made it out of the async buffer) is always captured.
+**Two layers now close the gap, each load-bearing on its own:**
 
-Signal inventory after a failed session: `[init] FAILED MCP servers: <names>` (names), `[mcp-init-error] server=<name> tail=…` (cause for each, from platform), optionally `[mcp:<name>] [<plugin>] …` (cause for each, from plugin's own sync-writes when the plugin is disciplined). Their union gives the investigator two independent sources for the same failure.
+1. **Plugin-side sync-write discipline.** Plugins that call `process.exit()` during module load (rare — `graph-mcp` is the in-tree example; it spawns a child at boot to proxy upstream stdio) use `fs.appendFileSync` at every named exit path to guarantee the cause lands in both log destinations before exit. Lines follow the `[mcp:<name>] [<plugin-prefix>] <cause>` format so existing `grep '[mcp:<name>]'` investigator paths work. Each destination is wrapped in its own try/catch — an unwritable log must not mask the primary failure. This is the discipline propagated from Task 560 to any plugin author who knows their failure paths.
+
+2. **Parent-side `mcp-spawn-tee` wrapper (Task 743).** Every node-based core MCP server is spawned via the `lib/mcp-spawn-tee` wrapper rather than `node <entry>` directly. The wrapper spawns the real entry with `stdio: ['inherit', 'inherit', 'pipe']` and writes child stderr chunks to `${LOG_DIR}/mcp-${name}-stderr-<date>.log` via `appendFileSync` while passing the same chunks through to its own stderr (Claude Code's consumer is unchanged). Synchronous `appendFileSync` survives `process.exit`, so the per-server file captures even (a) module-load throws before `initStderrTee` runs, (b) `MODULE_NOT_FOUND` on the entry script itself, and (c) anything else a plugin author missed. The wrapper writes `[mcp-spawn-tee-attached] server=<name> pid=<n>` on attach and forwards SIGTERM/SIGINT to the child. This is the layer that makes capture independent of plugin discipline. Playwright stays unwrapped because it spawns via `npx`, not `node`.
+
+A third layer closes the same gap from the platform side: when `claude-agent.ts` observes an `init` event with any MCP server reporting `status:"failed"`, it reads the last 512 bytes of `${LOG_DIR}/mcp-<name>-stderr-<date>.log` and emits `[mcp-init-error] server=<name> tail=<quoted>` into the stream log. Absent file → `tail="(no stderr file)"`; empty file → `tail="(empty)"`. With the spawn-tee wrapper now interposing on every core MCP, `tail="(no stderr file)"` post-Task-743 means the wrapper itself is broken — file follow-up.
+
+**Signal inventory after a failed session:** `[init] FAILED MCP servers: <names>` (names), `[mcp-init-error] server=<name> tail=…` (cause for each, from the platform's tail probe), `[mcp-spawn-tee-attached] server=<name> pid=<n>` (proof the wrapper attached), `[mcp-spawn-tee-exit] server=<name> code=<n>|signal=<s>` (proof the wrapper saw the exit), and optionally `[mcp:<name>] [<plugin>] …` from plugin-side sync-writes. Their union gives the investigator three independent sources for the same failure.
+
+**Boot-smoke as publish-time gate (Task 743).** The memory MCP carries `scripts/boot-smoke.sh` that spawns `dist/index.js` with stub env, sleeps 2s, asserts `kill -0 <pid>`, and reports `[boot-smoke] memory ok|FAILED tail=<n-lines>`. Wired to `prepublish` in `plugins/memory/mcp/package.json`. The pattern is propagatable to other plugin MCPs — it's deliberately not generalised yet because each plugin's stub-env requirements differ (memory needs ACCOUNT_ID + PLATFORM_ROOT + NEO4J_URI + SESSION_ID; others differ).

package/payload/platform/plugins/email/mcp/dist/lib/screening.d.ts

@@ -1,5 +1,5 @@
 /**
- * Email screening via Claude Haiku.
+ * Email screening via Claude Haiku (Task 740: OAuth, never API key — admin path).
  *
  * Classifies inbound emails before they enter Neo4j. Verdicts:
  *   clean      — legitimate correspondence, store normally
@@ -7,7 +7,7 @@
  *   discard    — obvious spam / bulk marketing / auto-generated noise, store without embedding
  *
  * On any failure the email defaults to "suspicious" (deny by default).
- * No file I/O — the API key is passed in by the caller.
+ * Auth: runs on Claude Code OAuth via `callOauthLlm`.
  */
 export interface ScreeningInput {
     fromAddress: string;
@@ -25,5 +25,5 @@ export interface ScreeningResult {
  * On any failure (network, auth, malformed response), returns
  * { verdict: "suspicious", reason: "<error>", promptInjectionRisk: false }.
  */
-export declare function screenEmail(input: ScreeningInput, apiKey: string): Promise<ScreeningResult>;
+export declare function screenEmail(input: ScreeningInput): Promise<ScreeningResult>;
 //# sourceMappingURL=screening.d.ts.map