@inhuman.tools/turn 0.1.0 → 0.3.0

package/src/resources/module-bundle.ts

@@ -0,0 +1,90 @@
+import { makeFsLoader, type Loader } from "@here.build/arrival-modules";
+
+export type ResourceIdentity = {
+  readonly id: string;
+  readonly revision: string;
+};
+
+export type ModuleBundle = ResourceIdentity & {
+  readonly loader: Loader;
+};
+
+export type ModuleBundleInput = ResourceIdentity & {
+  readonly modules: Readonly<Record<string, string>>;
+};
+
+/** Pins each resolved read, including failures; the host may persist it before evaluation proceeds. */
+export function pinModuleLoader(
+  loader: Loader,
+  capture?: (path: string, content: string) => void | Promise<void>,
+): Loader {
+  const reads = new Map<string, Promise<string>>();
+  return {
+    resolve: (specifier, fromDir) => loader.resolve(specifier, fromDir),
+    read(path) {
+      let read = reads.get(path);
+      if (read === undefined) {
+        read = Promise.resolve()
+          .then(() => loader.read(path))
+          .then(async (content) => {
+            const text = typeof content === "string" ? content : new TextDecoder().decode(content);
+            await capture?.(path, text);
+            return text;
+          });
+        reads.set(path, read);
+      }
+      return read;
+    },
+    resolvers: loader.resolvers,
+  };
+}
+
+function moduleKey(path: string): string {
+  if (path.startsWith("/") || /[\\\0]/.test(path) || /^[a-z][a-z\d+.-]*:/i.test(path)) {
+    throw new Error(`module is outside the resource namespace: ${path}`);
+  }
+  const segments: string[] = [];
+  for (const segment of path.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      if (segments.length === 0) throw new Error(`module escapes the resource namespace: ${path}`);
+      segments.pop();
+    } else {
+      segments.push(segment);
+    }
+  }
+  if (segments.length === 0) throw new Error("module key is empty");
+  return segments.join("/");
+}
+
+/** Captures content once; nested imports can only read this bundle's normalized keys. */
+export function createModuleBundle(input: ModuleBundleInput): ModuleBundle {
+  if (input.id.trim() === "" || input.revision.trim() === "") {
+    throw new Error("a module bundle requires an identity and revision");
+  }
+  const modules = new Map<string, string>();
+  for (const [path, content] of Object.entries(input.modules)) {
+    const key = moduleKey(path);
+    if (modules.has(key)) throw new Error(`duplicate normalized module: ${key}`);
+    modules.set(key, content);
+  }
+  const base = makeFsLoader({
+    readFile(path) {
+      const key = moduleKey(path);
+      const content = modules.get(key);
+      if (content === undefined) throw new Error(`module unavailable in ${input.id}@${input.revision}: ${key}`);
+      return content;
+    },
+  });
+  const loader: Loader = {
+    resolve(specifier, fromDir) {
+      if (specifier.startsWith("/") || /[\\\0]/.test(specifier) || /^[a-z][a-z\d+.-]*:/i.test(specifier)) {
+        throw new Error(`module is outside the resource namespace: ${specifier}`);
+      }
+      return base.resolve(specifier, fromDir);
+    },
+    read: (path) => base.read(path),
+    resolvers: base.resolvers,
+  };
+  return Object.freeze({ id: input.id, revision: input.revision, loader });
+}

package/src/runtime/ambient-compact.ts

@@ -0,0 +1,147 @@
+/**
+ * Ambient compact is a parallel isolated completion, not a tail splice.
+ * The turn does not wait.
+ *
+ * Who reads the summary: nothing in the product. `runCompactJob` and the
+ * compaction program build their own card from the full prefix and never
+ * consult it; the only thing read back is `ambientCompactKey` on the cutoff
+ * round, which stops the same prefix from starting a second summarizer. The
+ * summary is kept as the isolated completion's `responseText` so that a reader
+ * (a future cheap-cutoff path) has something to find. Until one exists the run
+ * is deliberately minimal: it holds the prefix text only while the request is
+ * in flight, then keeps the result and a reference, and completes.
+ */
+import {
+  CompletionExpectation,
+  CompletionJob,
+  PromptMessage,
+  type SessionTurn,
+} from "@inhuman.tools/harness-model/session";
+import type { CompleteRequest, CompleteResult } from "@inhuman.tools/harness-provider-sdk";
+
+import type { PromptMessageFactory, RuntimeDiagnostics } from "./ports.js";
+import { promptMessageOf } from "./prompt-message-of.js";
+import { textOfCell, Transcript } from "../context/index.js";
+
+const SNAPSHOT_SYSTEM = `Fold this conversation prefix into a reference snapshot. Keep decisions, constraints, errors, and unresolved work. Drop tool chatter the snapshot does not need. Do not address the reader. Do not list next steps.`;
+
+function kvTrim(kvs: Readonly<Record<string, string>>, key: string): string {
+  if (!Object.hasOwn(kvs, key)) return "";
+  return kvs[key].trim();
+}
+
+export function ambientModel(kvs: Readonly<Record<string, string>>, fallback: string): string {
+  const named = kvTrim(kvs, "models.summarizer") || kvTrim(kvs, ":models.summarizer");
+  return named !== "" ? named : fallback.trim();
+}
+
+/** First kept round. The summary of everything older hangs here. */
+export function ambientCutoff(keep: Transcript): CompletionJob | null {
+  for (const cell of keep.cells) {
+    if (cell instanceof CompletionJob) return cell;
+    if (cell instanceof CompletionExpectation && cell.parent instanceof CompletionJob) return cell.parent;
+  }
+  return null;
+}
+
+export function ambientKey(prefix: Transcript, focus: string): string {
+  const head = textOfCell(prefix.cells[0]).slice(0, 80);
+  const tail = textOfCell(prefix.cells.at(-1)).slice(0, 80);
+  return `${prefix.cells.length}\0${prefix.tokensUsed()}\0${head}\0${tail}\0${focus}`;
+}
+
+/**
+ * Fire a summarizer beside the turn. Returns the settlement promise so a test
+ * can observe it; the turn loop must not await it.
+ */
+export function startAmbientCompact(opts: {
+  readonly home: SessionTurn;
+  readonly cutoff: CompletionJob;
+  readonly prefix: Transcript;
+  readonly focus: string;
+  readonly connectionId: string;
+  readonly model: string;
+  readonly complete: (req: CompleteRequest) => Promise<CompleteResult>;
+  readonly inflight: Map<CompletionJob, string>;
+  readonly message?: PromptMessageFactory;
+  readonly diagnostics?: RuntimeDiagnostics;
+}): Promise<void> {
+  const key = ambientKey(opts.prefix, opts.focus);
+  if (opts.cutoff.ambientCompactKey === key) return Promise.resolve();
+  if (opts.inflight.get(opts.cutoff) === key) return Promise.resolve();
+  const transcript = opts.prefix.cells
+    .map((cell) => textOfCell(cell))
+    .filter((line) => line !== "")
+    .join("\n\n");
+  if (transcript === "" || opts.connectionId === "" || opts.model === "") return Promise.resolve();
+  opts.inflight.set(opts.cutoff, key);
+  return runAmbientCompact(opts, key, transcript);
+}
+
+async function runAmbientCompact(
+  opts: {
+    readonly home: SessionTurn;
+    readonly cutoff: CompletionJob;
+    readonly focus: string;
+    readonly connectionId: string;
+    readonly model: string;
+    readonly complete: (req: CompleteRequest) => Promise<CompleteResult>;
+    readonly inflight: Map<CompletionJob, string>;
+    readonly message?: PromptMessageFactory;
+    readonly diagnostics?: RuntimeDiagnostics;
+  },
+  key: string,
+  transcript: string,
+): Promise<void> {
+  const user = opts.focus === "" ? transcript : `${transcript}\n\nEmphasize:\n${opts.focus}`;
+  let job: CompletionJob | null = null;
+  try {
+    const round = new CompletionExpectation({
+      connectionId: opts.connectionId,
+      model: opts.model,
+      completionMode: "isolated",
+      reasoningEffort: "none",
+      // The transcript prefix is the whole conversation again: past the inline limit it lives in the blob
+      // bucket and the document keeps its head.
+      promptMessages: [
+        (opts.message ?? promptMessageOf)("system", SNAPSHOT_SYSTEM),
+        (opts.message ?? promptMessageOf)("user", user),
+      ],
+    });
+    job = new CompletionJob({ expectation: round });
+    opts.home.pushChild(job);
+    await opts.complete({
+      connectionId: opts.connectionId,
+      model: opts.model,
+      promptText: round.userPrompt,
+      round,
+    });
+    if (opts.inflight.get(opts.cutoff) !== key) return;
+    const text = round.responseText.trim();
+    if (round.outcome !== "successful" || text === "") return;
+    // The summary stays on the isolated completion (the result). The key is what
+    // stops the next round with this prefix from starting another summarizer.
+    opts.cutoff.ambientCompactKey = key;
+  } catch (error) {
+    if (opts.inflight.get(opts.cutoff) === key) opts.diagnostics?.fail?.("ambient compact", error);
+  } finally {
+    if (job != null) settleAmbientJob(job, key, opts.focus);
+    if (opts.inflight.get(opts.cutoff) === key) opts.inflight.delete(opts.cutoff);
+  }
+}
+
+/**
+ * A settled ambient run keeps its result and a reference to what it summarized,
+ * not the copy of the prefix it was asked about: that copy is the whole
+ * conversation again and nothing reads it. The job is then complete, however
+ * the run ended (a newer prefix winning counts), so it is not left open.
+ */
+function settleAmbientJob(job: CompletionJob, key: string, focus: string): void {
+  const round = job.expectation;
+  if (!round.isDone) return;
+  const [cells = "?", tokens = "?"] = key.split("\0");
+  const ref = [`ambient compact of a prefix of ${cells} cells, ${tokens} tokens`];
+  if (focus !== "") ref.push(`focus: ${focus}`);
+  round.promptMessages = [new PromptMessage({ role: "user", content: ref.join("\n") })];
+  if (!job.completed) job.markComplete();
+}

package/src/runtime/index.ts

@@ -0,0 +1,17 @@
+export { iterateTurn, type TurnIteratorHost } from "./turn-iterator.js";
+export { createTurnResolvers, type TurnResolverHost, type TurnResolvers } from "./turn-resolvers.js";
+export {
+  type RuntimeLoopNote,
+  type RuntimeNoteLog,
+  type TurnSettle,
+  type RuntimeDiagnostics,
+  type PromptTextStamp,
+  type PromptTextExternalizer,
+  type PromptMessageFactory,
+} from "./ports.js";
+export { promptMessageOf } from "./prompt-message-of.js";
+export { ambientCutoff, ambientKey, ambientModel, startAmbientCompact } from "./ambient-compact.js";
+export * from "./re-act-loop-intent-detected-trigger.js";
+export { CONTENT_FILTER_STOP, LENGTH_STOP, refusalText, maxRoundsMessage, roundCapReached } from "./round-stop.js";
+
+export * from "../session-runtime/index.js";

package/src/runtime/ports.ts

@@ -0,0 +1,28 @@
+import type { PromptMessage, PromptMessageRole } from "@inhuman.tools/harness-model/session";
+
+export type RuntimeLoopNote = {
+  readonly id: string;
+  readonly text: string;
+  readonly mode: "ambient" | "activating";
+};
+
+export interface RuntimeNoteLog {
+  peek(sessionId: string): readonly RuntimeLoopNote[];
+  consume(sessionId: string, ids: readonly string[], callId: string): void;
+}
+
+export type TurnSettle =
+  { readonly ok: true; readonly value: string | false } | { readonly ok: false; readonly error: string };
+
+export interface RuntimeDiagnostics {
+  step?(message: string): void;
+  trace?(namespace: string, message: string): void;
+  fail?(label: string, error: unknown): void;
+}
+
+export type PromptTextStamp =
+  | { readonly kind: "inline"; readonly text: string }
+  | { readonly kind: "blob"; readonly head: string; readonly blobJson: string };
+
+export type PromptTextExternalizer = (text: string) => PromptTextStamp;
+export type PromptMessageFactory = (role: PromptMessageRole, text: string) => PromptMessage;

package/src/runtime/prompt-message-of.ts

@@ -0,0 +1,14 @@
+import { PromptMessage, type PromptMessageRole } from "@inhuman.tools/harness-model/session";
+
+import type { PromptTextExternalizer } from "./ports.js";
+
+export function promptMessageOf(
+  role: PromptMessageRole,
+  text: string,
+  externalize?: PromptTextExternalizer,
+): PromptMessage {
+  const stamp = externalize?.(text) ?? { kind: "inline", text };
+  return stamp.kind === "inline"
+    ? new PromptMessage({ role, content: stamp.text })
+    : new PromptMessage({ role, content: stamp.head, contentBlobJson: stamp.blobJson });
+}

package/src/runtime/re-act-loop-intent-detected-trigger.ts

@@ -0,0 +1,177 @@
+/**
+ * Text-only continuation intern (A). Isolated json_schema, judge wire,
+ * one shot. Returns a typed assessment, including unavailability; it never
+ * authorizes a model invocation itself. The round boundary owns arbitration.
+ */
+import {
+  clipSpeech,
+  INTERN_SYSTEM,
+  LENGTH_CONTINUE_NOTE as CORE_LENGTH_NOTE,
+  RE_ACT_LOOP_INTENT_DETECTED_TRIGGER_NOTE as CORE_RE_ACT_NOTE,
+  RE_ACT_LOOP_INTENT_DETECTED_TRIGGER_TIMEOUT_MS,
+  THOUGHT_CONTINUE_NOTE as CORE_THOUGHT_NOTE,
+  verdictOf,
+} from "@inhuman.tools/continuation";
+import { prompt } from "@inhuman.tools/harness-commons";
+import {
+  CompletionExpectation,
+  type IntentAssessment,
+  CompletionJob,
+  flattenOverviewLine,
+  GLANCE_ASK_LINE_MAX_CHARS,
+  isJsonSchemaUnsupported,
+  SessionTurn,
+} from "@inhuman.tools/harness-model/session";
+import {
+  parseTextOnlyContinueVote,
+  RE_ACT_LOOP_INTENT_DETECTED_TRIGGER_RESPONSE_SCHEMA,
+} from "@inhuman.tools/harness-model/shared";
+import type { CompleteRequest, CompleteResult } from "@inhuman.tools/harness-provider-sdk";
+import { splitThink } from "@inhuman.tools/tool-call-normalize";
+
+import type { PromptMessageFactory } from "./ports.js";
+import { promptMessageOf } from "./prompt-message-of.js";
+
+export {
+  clipSpeech,
+  INTERN_SYSTEM,
+  RE_ACT_LOOP_INTENT_DETECTED_TRIGGER_SPEECH_CHARS,
+  RE_ACT_LOOP_INTENT_DETECTED_TRIGGER_TIMEOUT_MS,
+  THOUGHT_WITHOUT_ANSWER_STREAK_MAX,
+  verdictOf,
+  type ReActLoopIntentDetectedTriggerVerdict,
+} from "@inhuman.tools/continuation";
+
+export const RE_ACT_LOOP_INTENT_DETECTED_TRIGGER_NOTE = prompt.system`${CORE_RE_ACT_NOTE}`;
+
+export const THOUGHT_CONTINUE_NOTE = prompt.system`${CORE_THOUGHT_NOTE}`;
+
+export const LENGTH_CONTINUE_NOTE = prompt.system`${CORE_LENGTH_NOTE}`;
+
+export type InternJudgeWire = {
+  readonly connection: string;
+  readonly model: string;
+  readonly key: string;
+};
+
+export function internJudgeWire(
+  kvs: Readonly<Record<string, string>>,
+  fallback: Readonly<Record<string, string>>,
+  configuredModel: (connectionId: string) => string,
+): InternJudgeWire | null {
+  const connection = (kvs.judgeConnection || fallback.judgeConnection || "").trim();
+  const named = (kvs.judgeModel || fallback.judgeModel || "").trim();
+  const configured = connection !== "" ? configuredModel(connection).trim() : "";
+  const model = (named || configured).trim();
+  if (connection === "" || model === "") return null;
+  return { connection, model, key: `${connection}\n${model}` };
+}
+
+export function questionLineFromSpeech(text: string): string {
+  const line = flattenOverviewLine(splitThink(text).content, GLANCE_ASK_LINE_MAX_CHARS);
+  return line === "" ? "has a question" : line;
+}
+
+/**
+ * A thinking channel with no spoken answer. The round has not finished.
+ * Visible CoT, a think-tag that is the whole message, encrypted reasoning,
+ * billed reasoning tokens, or a stamped thought kind (redacted / empty
+ * thinking part) are the same event: thought without an answer.
+ */
+export function thoughtWithoutAnswer(pew: CompletionExpectation): boolean {
+  const split = splitThink(pew.responseText);
+  if (split.content.trim() !== "") return false;
+  if (`${pew.responseThought}\n${split.reasoning}`.trim() !== "") return true;
+  if (pew.responseReasoningEncrypted.trim() !== "") return true;
+  if ((pew.reasoningTokens ?? 0) > 0) return true;
+  return pew.responseThoughtKind != null;
+}
+
+export type ReActLoopIntentDetectedTriggerComplete = (req: CompleteRequest) => Promise<CompleteResult>;
+
+export async function assessTextOnlyContinueIntern(opts: {
+  readonly speech: string;
+  readonly wire: InternJudgeWire;
+  readonly haltKeys: Set<string>;
+  readonly home: SessionTurn;
+  readonly complete: ReActLoopIntentDetectedTriggerComplete;
+  readonly signal: AbortSignal;
+  readonly message?: PromptMessageFactory;
+}): Promise<IntentAssessment> {
+  if (opts.haltKeys.has(opts.wire.key))
+    return { verdict: null, status: "unsupported", detail: "Continuation judge does not support structured output." };
+  const speech = clipSpeech(splitThink(opts.speech).content);
+  const intern = new CompletionExpectation({
+    connectionId: opts.wire.connection,
+    model: opts.wire.model,
+    completionMode: "isolated",
+    reasoningEffort: "none",
+    promptMessages: [
+      (opts.message ?? promptMessageOf)("system", INTERN_SYSTEM),
+      (opts.message ?? promptMessageOf)("user", speech),
+    ],
+    responseSchema: RE_ACT_LOOP_INTENT_DETECTED_TRIGGER_RESPONSE_SCHEMA,
+  });
+  const job = new CompletionJob({ expectation: intern });
+  opts.home.pushChild(job);
+  const internAbort = AbortSignal.any([
+    opts.signal,
+    AbortSignal.timeout(RE_ACT_LOOP_INTENT_DETECTED_TRIGGER_TIMEOUT_MS),
+  ]);
+  let stopWaiting = (): void => {};
+  try {
+    internAbort.throwIfAborted();
+    const aborted = new Promise<never>((_resolve, reject) => {
+      const onAbort = (): void => reject(internAbort.reason ?? new Error("Continuation judge aborted."));
+      stopWaiting = () => internAbort.removeEventListener("abort", onAbort);
+      if (internAbort.aborted) onAbort();
+      else internAbort.addEventListener("abort", onAbort, { once: true });
+    });
+    await Promise.race([
+      opts.complete({
+        connectionId: opts.wire.connection,
+        model: opts.wire.model,
+        promptText: intern.userPrompt,
+        responseSchemaJson: intern.responseSchema == null ? undefined : JSON.stringify(intern.responseSchema),
+        round: intern,
+        signal: internAbort,
+      }),
+      aborted,
+    ]);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (isJsonSchemaUnsupported(message)) opts.haltKeys.add(opts.wire.key);
+    if (intern.outcome == null) {
+      intern.failReason = message;
+      intern.fail("crash", message, "null");
+    }
+    return {
+      verdict: null,
+      status: isJsonSchemaUnsupported(message)
+        ? "unsupported"
+        : message.includes("response schema:")
+          ? "invalid"
+          : "failed",
+      detail: message,
+    };
+  } finally {
+    stopWaiting();
+    job.completed = true;
+  }
+  if (intern.outcome !== "successful") {
+    const detail = intern.failReason?.trim() || intern.endDetail?.trim() || "Continuation judge failed.";
+    if (isJsonSchemaUnsupported(detail)) opts.haltKeys.add(opts.wire.key);
+    return {
+      verdict: null,
+      status: isJsonSchemaUnsupported(detail)
+        ? "unsupported"
+        : detail.includes("response schema:")
+          ? "invalid"
+          : "failed",
+      detail,
+    };
+  }
+  const vote = parseTextOnlyContinueVote(intern.responseText);
+  if (vote == null) return { verdict: null, status: "invalid", detail: "Continuation judge returned an invalid vote." };
+  return { verdict: verdictOf(vote), status: "judged", detail: "" };
+}