@zwbigi/ink-xy 0.1.2 → 0.1.4

package/inkos/packages/core/src/interaction/session-transcript.ts

@@ -0,0 +1,189 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { AgentMessage } from "@mariozechner/pi-agent-core";
+import { TranscriptEventSchema, type TranscriptEvent } from "./session-transcript-schema.js";
+import type { TranscriptRole } from "./session-transcript-schema.js";
+
+const SESSIONS_DIR = ".inkos/sessions";
+const appendQueues = new Map<string, Promise<void>>();
+
+export function sessionsDir(projectRoot: string): string {
+  return join(projectRoot, SESSIONS_DIR);
+}
+
+export function transcriptPath(projectRoot: string, sessionId: string): string {
+  return join(sessionsDir(projectRoot), `${sessionId}.jsonl`);
+}
+
+export function legacyBookSessionPath(projectRoot: string, sessionId: string): string {
+  return join(sessionsDir(projectRoot), `${sessionId}.json`);
+}
+
+export async function readTranscriptEvents(
+  projectRoot: string,
+  sessionId: string,
+): Promise<TranscriptEvent[]> {
+  let raw: string;
+  try {
+    raw = await readFile(transcriptPath(projectRoot, sessionId), "utf-8");
+  } catch {
+    return [];
+  }
+
+  const events: TranscriptEvent[] = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = TranscriptEventSchema.safeParse(JSON.parse(line));
+      if (parsed.success) events.push(parsed.data);
+    } catch {
+      continue;
+    }
+  }
+
+  return events.sort((a, b) => a.seq - b.seq);
+}
+
+export async function nextTranscriptSeq(projectRoot: string, sessionId: string): Promise<number> {
+  const events = await readTranscriptEvents(projectRoot, sessionId);
+  return events.reduce((max, event) => Math.max(max, event.seq), 0) + 1;
+}
+
+export async function appendTranscriptEvent(
+  projectRoot: string,
+  event: TranscriptEvent,
+): Promise<void> {
+  await appendTranscriptEvents(projectRoot, event.sessionId, () => [event]);
+}
+
+export async function appendTranscriptEvents(
+  projectRoot: string,
+  sessionId: string,
+  buildEvents: (context: {
+    readonly events: ReadonlyArray<TranscriptEvent>;
+    readonly nextSeq: number;
+  }) => ReadonlyArray<TranscriptEvent> | Promise<ReadonlyArray<TranscriptEvent>>,
+): Promise<TranscriptEvent[]> {
+  const key = `${projectRoot}:${sessionId}`;
+  const previous = appendQueues.get(key) ?? Promise.resolve();
+  let result: TranscriptEvent[] = [];
+
+  const next = previous.then(async () => {
+    const events = await readTranscriptEvents(projectRoot, sessionId);
+    const nextSeq = events.reduce((max, event) => Math.max(max, event.seq), 0) + 1;
+    const built = await buildEvents({ events, nextSeq });
+    result = built.map((event) => TranscriptEventSchema.parse(event));
+    if (result.length === 0) return;
+
+    await mkdir(sessionsDir(projectRoot), { recursive: true });
+    await appendFile(
+      transcriptPath(projectRoot, sessionId),
+      `${result.map((event) => JSON.stringify(event)).join("\n")}\n`,
+      "utf-8",
+    );
+  });
+
+  appendQueues.set(key, next.catch(() => undefined));
+  await next;
+  return result;
+}
+
+function transcriptRoleForMessage(message: AgentMessage): TranscriptRole | null {
+  if (!message || typeof message !== "object" || !("role" in message)) return null;
+  const role = (message as { role?: unknown }).role;
+  return role === "user" || role === "assistant" || role === "toolResult" || role === "system"
+    ? role
+    : null;
+}
+
+function messageTimestamp(message: AgentMessage): number {
+  if (message && typeof message === "object") {
+    const timestamp = (message as { timestamp?: unknown }).timestamp;
+    if (typeof timestamp === "number" && Number.isFinite(timestamp) && timestamp >= 0) {
+      return Math.floor(timestamp);
+    }
+  }
+  return Date.now();
+}
+
+function toolCallIdForMessage(message: AgentMessage): string | undefined {
+  if (!message || typeof message !== "object") return undefined;
+  if ((message as { role?: unknown }).role === "toolResult") {
+    const toolCallId = (message as { toolCallId?: unknown }).toolCallId;
+    return typeof toolCallId === "string" && toolCallId.length > 0 ? toolCallId : undefined;
+  }
+
+  const content = (message as { content?: unknown }).content;
+  if (!Array.isArray(content)) return undefined;
+  const block = content.find(
+    (item): item is { type: "toolCall"; id: string } =>
+      !!item &&
+      typeof item === "object" &&
+      (item as { type?: unknown }).type === "toolCall" &&
+      typeof (item as { id?: unknown }).id === "string",
+  );
+  return block?.id;
+}
+
+export async function appendManualSessionMessages(
+  projectRoot: string,
+  sessionId: string,
+  messages: ReadonlyArray<AgentMessage>,
+  input = "",
+): Promise<void> {
+  const persistedMessages = messages
+    .map((message) => ({ message, role: transcriptRoleForMessage(message) }))
+    .filter((entry): entry is { message: AgentMessage; role: TranscriptRole } => entry.role !== null);
+  if (persistedMessages.length === 0) return;
+
+  const requestId = randomUUID();
+  await appendTranscriptEvents(projectRoot, sessionId, ({ nextSeq }) => {
+    let seq = nextSeq;
+    const events: TranscriptEvent[] = [{
+      type: "request_started",
+      version: 1,
+      sessionId,
+      requestId,
+      seq: seq++,
+      timestamp: Date.now(),
+      input,
+    }];
+
+    let parentUuid: string | null = null;
+    let lastAssistantUuid: string | null = null;
+    for (const { message, role } of persistedMessages) {
+      const uuid = randomUUID();
+      const isToolResult = role === "toolResult";
+      const toolCallId = toolCallIdForMessage(message);
+      events.push({
+        type: "message",
+        version: 1,
+        sessionId,
+        requestId,
+        uuid,
+        parentUuid: isToolResult && lastAssistantUuid ? lastAssistantUuid : parentUuid,
+        seq: seq++,
+        role,
+        timestamp: messageTimestamp(message),
+        ...(toolCallId ? { toolCallId } : {}),
+        ...(isToolResult && lastAssistantUuid
+          ? { sourceToolAssistantUuid: lastAssistantUuid }
+          : {}),
+        message,
+      });
+      if (role === "assistant") lastAssistantUuid = uuid;
+      parentUuid = uuid;
+    }
+
+    events.push({
+      type: "request_committed",
+      version: 1,
+      sessionId,
+      requestId,
+      seq,
+      timestamp: Date.now(),
+    });
+    return events;
+  });
+}

package/inkos/packages/core/src/interaction/session.ts

@@ -0,0 +1,226 @@
+import { z } from "zod";
+import { AutomationModeSchema, type AutomationMode } from "./modes.js";
+import { ExecutionStateSchema, InteractionEventSchema, type InteractionEvent } from "./events.js";
+import { assertSafeBookId, isSafeBookId } from "../utils/book-id.js";
+
+export const PendingDecisionSchema = z.object({
+  kind: z.string().min(1),
+  bookId: z.string().min(1),
+  chapterNumber: z.number().int().min(1).optional(),
+  summary: z.string().min(1),
+});
+
+export type PendingDecision = z.infer<typeof PendingDecisionSchema>;
+
+export const PipelineStageSchema = z.object({
+  label: z.string(),
+  status: z.enum(["pending", "active", "completed"]),
+});
+
+export type PipelineStage = z.infer<typeof PipelineStageSchema>;
+
+export const ToolExecutionSchema = z.object({
+  id: z.string(),
+  tool: z.string(),
+  agent: z.string().optional(),
+  label: z.string(),
+  status: z.enum(["running", "processing", "completed", "error"]),
+  args: z.record(z.unknown()).optional(),
+  result: z.string().optional(),
+  details: z.unknown().optional(),
+  error: z.string().optional(),
+  stages: z.array(PipelineStageSchema).optional(),
+  startedAt: z.number(),
+  completedAt: z.number().optional(),
+});
+
+export type ToolExecution = z.infer<typeof ToolExecutionSchema>;
+
+export const InteractionMessageSchema = z.object({
+  role: z.enum(["user", "assistant", "system"]),
+  content: z.string().min(1),
+  thinking: z.string().optional(),
+  toolExecutions: z.array(ToolExecutionSchema).optional(),
+  timestamp: z.number().int().nonnegative(),
+});
+
+export type InteractionMessage = z.infer<typeof InteractionMessageSchema>;
+
+export const BookCreationDraftSchema = z.object({
+  concept: z.string().min(1),
+  title: z.string().min(1).optional(),
+  genre: z.string().min(1).optional(),
+  platform: z.string().min(1).optional(),
+  language: z.enum(["zh", "en"]).optional(),
+  targetChapters: z.number().int().min(1).optional(),
+  chapterWordCount: z.number().int().min(1).optional(),
+  blurb: z.string().min(1).optional(),
+  worldPremise: z.string().min(1).optional(),
+  settingNotes: z.string().min(1).optional(),
+  protagonist: z.string().min(1).optional(),
+  supportingCast: z.string().min(1).optional(),
+  conflictCore: z.string().min(1).optional(),
+  volumeOutline: z.string().min(1).optional(),
+  constraints: z.string().min(1).optional(),
+  authorIntent: z.string().min(1).optional(),
+  currentFocus: z.string().min(1).optional(),
+  nextQuestion: z.string().min(1).optional(),
+  missingFields: z.array(z.string().min(1)).default([]),
+  readyToCreate: z.boolean().default(false),
+});
+
+export type BookCreationDraft = z.infer<typeof BookCreationDraftSchema>;
+
+export const DraftRoundSchema = z.object({
+  roundId: z.number().int().min(1),
+  userMessage: z.string(),
+  assistantRaw: z.string(),
+  fieldsUpdated: z.array(z.string()).default([]),
+  summary: z.string().default(""),
+  timestamp: z.number().int().nonnegative(),
+});
+
+export type DraftRound = z.infer<typeof DraftRoundSchema>;
+
+export const InteractionSessionSchema = z.object({
+  sessionId: z.string().min(1),
+  projectRoot: z.string().min(1),
+  activeBookId: z.string().min(1).optional(),
+  activeChapterNumber: z.number().int().min(1).optional(),
+  creationDraft: BookCreationDraftSchema.optional(),
+  draftRounds: z.array(DraftRoundSchema).default([]),
+  automationMode: AutomationModeSchema.default("semi"),
+  messages: z.array(InteractionMessageSchema).default([]),
+  events: z.array(InteractionEventSchema).default([]),
+  pendingDecision: PendingDecisionSchema.optional(),
+  currentExecution: ExecutionStateSchema.optional(),
+});
+
+export type InteractionSession = z.infer<typeof InteractionSessionSchema>;
+
+// -- Per-book session --
+
+export const BookSessionSchema = z.object({
+  sessionId: z.string().min(1),
+  bookId: z.string().refine(isSafeBookId, "Invalid bookId").nullable(),
+  title: z.string().nullable().default(null),
+  messages: z.array(InteractionMessageSchema).default([]),
+  creationDraft: BookCreationDraftSchema.optional(),
+  draftRounds: z.array(DraftRoundSchema).default([]),
+  events: z.array(InteractionEventSchema).default([]),
+  currentExecution: ExecutionStateSchema.optional(),
+  createdAt: z.number().int().nonnegative(),
+  updatedAt: z.number().int().nonnegative(),
+});
+
+export type BookSession = z.infer<typeof BookSessionSchema>;
+
+// -- Global session (simplified) --
+
+export const GlobalSessionSchema = z.object({
+  activeBookId: z.string().refine(isSafeBookId, "Invalid activeBookId").optional(),
+  automationMode: AutomationModeSchema.default("semi"),
+});
+
+export type GlobalSession = z.infer<typeof GlobalSessionSchema>;
+
+export function createBookSession(bookId: string | null, sessionId?: string): BookSession {
+  const now = Date.now();
+  const safeBookId = bookId === null ? null : assertSafeBookId(bookId);
+  return {
+    sessionId: sessionId ?? `${now}-${Math.random().toString(36).slice(2, 8)}`,
+    bookId: safeBookId,
+    title: null,
+    messages: [],
+    draftRounds: [],
+    events: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+export function appendBookSessionMessage(
+  session: BookSession,
+  message: InteractionMessage,
+): BookSession {
+  return {
+    ...session,
+    messages: [...session.messages, message].sort((a, b) => a.timestamp - b.timestamp),
+    updatedAt: Date.now(),
+  };
+}
+
+export function bindActiveBook(
+  session: InteractionSession,
+  bookId: string,
+  chapterNumber?: number,
+): InteractionSession {
+  return {
+    ...session,
+    activeBookId: bookId,
+    ...(chapterNumber !== undefined ? { activeChapterNumber: chapterNumber } : {}),
+  };
+}
+
+export function clearPendingDecision(session: InteractionSession): InteractionSession {
+  if (!session.pendingDecision) {
+    return session;
+  }
+
+  return {
+    ...session,
+    pendingDecision: undefined,
+  };
+}
+
+export function updateCreationDraft(
+  session: InteractionSession,
+  draft: BookCreationDraft,
+): InteractionSession {
+  return {
+    ...session,
+    creationDraft: draft,
+  };
+}
+
+export function clearCreationDraft(session: InteractionSession): InteractionSession {
+  if (!session.creationDraft) {
+    return session;
+  }
+
+  return {
+    ...session,
+    creationDraft: undefined,
+    draftRounds: [],
+  };
+}
+
+export function updateAutomationMode(
+  session: InteractionSession,
+  automationMode: AutomationMode,
+): InteractionSession {
+  return {
+    ...session,
+    automationMode,
+  };
+}
+
+export function appendInteractionMessage(
+  session: InteractionSession,
+  message: InteractionMessage,
+): InteractionSession {
+  return {
+    ...session,
+    messages: [...session.messages, message].sort((left, right) => left.timestamp - right.timestamp),
+  };
+}
+
+export function appendInteractionEvent(
+  session: InteractionSession,
+  event: InteractionEvent,
+): InteractionSession {
+  return {
+    ...session,
+    events: [...session.events, event],
+  };
+}

package/inkos/packages/core/src/interaction/truth-authority.ts

@@ -0,0 +1,45 @@
+export type TruthAuthority =
+  | "direction"
+  | "foundation"
+  | "rules"
+  | "runtime-truth"
+  | "memory";
+
+const NORMALIZED_TRUTH_FILES = new Set([
+  "author_intent.md",
+  "current_focus.md",
+  "story_bible.md",
+  "volume_outline.md",
+  "book_rules.md",
+  "current_state.md",
+  "pending_hooks.md",
+  "chapter_summaries.md",
+]);
+
+export function normalizeTruthFileName(fileName: string): string {
+  const trimmed = fileName.trim().toLowerCase();
+  const normalized = trimmed.endsWith(".md") ? trimmed : `${trimmed}.md`;
+  if (!NORMALIZED_TRUTH_FILES.has(normalized)) {
+    return normalized;
+  }
+  return normalized;
+}
+
+export function classifyTruthAuthority(fileName: string): TruthAuthority {
+  switch (normalizeTruthFileName(fileName)) {
+    case "author_intent.md":
+    case "current_focus.md":
+      return "direction";
+    case "story_bible.md":
+    case "volume_outline.md":
+      return "foundation";
+    case "book_rules.md":
+      return "rules";
+    case "current_state.md":
+    case "pending_hooks.md":
+      return "runtime-truth";
+    case "chapter_summaries.md":
+    default:
+      return "memory";
+  }
+}

package/inkos/packages/core/src/llm/config-migration.ts

@@ -0,0 +1,58 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { saveSecrets, loadSecrets } from "./secrets.js";
+import { guessServiceFromBaseUrl } from "./service-presets.js";
+
+export interface MigrationResult {
+  migrated: boolean;
+}
+
+export async function migrateConfig(projectRoot: string): Promise<MigrationResult> {
+  const configPath = join(projectRoot, "inkos.json");
+  let raw: string;
+  try {
+    raw = await readFile(configPath, "utf-8");
+  } catch {
+    return { migrated: false };
+  }
+
+  const config = JSON.parse(raw);
+  const llm = config.llm;
+  if (!llm) return { migrated: false };
+
+  // Already new format
+  if (Array.isArray(llm.services)) return { migrated: false };
+
+  // Old format: llm.provider, llm.model, llm.baseUrl, llm.apiKey
+  const { provider, model, baseUrl, apiKey, ...restLlm } = llm;
+  if (!model && !provider) return { migrated: false };
+
+  // Determine service from baseUrl
+  const guessedService = baseUrl ? guessServiceFromBaseUrl(baseUrl) : null;
+  const service = guessedService ?? "custom";
+
+  // Build new service entry
+  const serviceEntry: Record<string, string> = { service };
+  if (service === "custom") {
+    serviceEntry.name = "Custom";
+    if (baseUrl) serviceEntry.baseUrl = baseUrl;
+  }
+
+  // Write new config (no apiKey)
+  config.llm = {
+    ...restLlm,
+    services: [serviceEntry],
+    defaultModel: model,
+  };
+  await writeFile(configPath, JSON.stringify(config, null, 2), "utf-8");
+
+  // Move apiKey to secrets
+  if (apiKey) {
+    const secrets = await loadSecrets(projectRoot);
+    const secretKey = service === "custom" ? `custom:${serviceEntry.name}` : service;
+    secrets.services[secretKey] = { apiKey };
+    await saveSecrets(projectRoot, secrets);
+  }
+
+  return { migrated: true };
+}

package/inkos/packages/core/src/llm/cover-providers.ts

@@ -0,0 +1,45 @@
+export type CoverProviderId = "kkaiapi" | "openai" | "google";
+
+export interface CoverProviderPreset {
+  readonly service: CoverProviderId;
+  readonly label: string;
+  readonly baseUrl: string;
+  readonly api: "responses" | "images" | "gemini";
+  readonly defaultModel: string;
+  readonly models: readonly string[];
+}
+
+export const COVER_PROVIDER_PRESETS: readonly CoverProviderPreset[] = [
+  {
+    service: "kkaiapi",
+    label: "kkaiapi",
+    baseUrl: "https://api.kkaiapi.com/v1",
+    api: "images",
+    defaultModel: "gpt-image-2",
+    models: ["gpt-image-2"],
+  },
+  {
+    service: "openai",
+    label: "OpenAI Images",
+    baseUrl: "https://api.openai.com/v1",
+    api: "images",
+    defaultModel: "gpt-image-2",
+    models: ["gpt-image-2"],
+  },
+  {
+    service: "google",
+    label: "Google Gemini",
+    baseUrl: "https://generativelanguage.googleapis.com/v1beta",
+    api: "gemini",
+    defaultModel: "gemini-3.1-flash-image-preview",
+    models: ["gemini-3.1-flash-image-preview", "gemini-2.5-flash-image"],
+  },
+];
+
+export function resolveCoverProviderPreset(service: string | undefined): CoverProviderPreset | undefined {
+  return COVER_PROVIDER_PRESETS.find((provider) => provider.service === service);
+}
+
+export function coverSecretKey(service: string): string {
+  return `cover:${service}`;
+}