@inhuman.tools/harness-scheme 0.0.0-stage → 0.2.0

package/src/file-path.ts

@@ -0,0 +1 @@
+export { filePathOf, stampFilePath } from "@inhuman.tools/scheme-program";

package/src/index.ts

@@ -0,0 +1,17 @@
+export * from "./env.js";
+
+export * from "./interpret.js";
+
+export * from "./keywords.js";
+
+export * from "./bound-tools.js";
+
+export * from "./catalog-description.js";
+
+export * from "./connection-models.js";
+
+export * from "./program-source.js";
+
+export * from "./limits.js";
+
+export * from "./file-path.js";

package/src/interpret.ts

@@ -0,0 +1,26 @@
+/**
+ * ProgrammaticJob body. SessionTurn waits on the bag. Not PEW and not
+ * catalog `execute`.
+ *
+ * `runProgram` and `runWatch` own the evaluation. This builds the ProgramHost
+ * — vocabulary lands on the first `prepare` — and calls one of them with the
+ * job. A watch job must take `runWatch`: the first prepare wins, and only
+ * that call roots meta-reactivity.
+ */
+import { ProgrammaticJob, SCHEME_WATCH_TOOL_NAME } from "@inhuman.tools/harness-model";
+import { runProgram } from "@inhuman.tools/scheme-program";
+import { programSourceLoader } from "@inhuman.tools/scheme-program/fs";
+import { runWatch } from "@inhuman.tools/scheme-watch";
+
+import { programHostOf, type SchemeReplHost } from "./env.js";
+
+export async function interpretSchemeRepl(chunk: ProgrammaticJob, host: SchemeReplHost): Promise<void> {
+  if (host.loadSource == null && host.replayOnly !== true) {
+    Object.assign(host, {
+      loadSource: (root: string, job: ProgrammaticJob) => programSourceLoader(root, job),
+    });
+  }
+  const programHost = programHostOf(host);
+  if (chunk.toolName === SCHEME_WATCH_TOOL_NAME) return runWatch(chunk, programHost);
+  return runProgram(chunk, programHost);
+}

package/src/keywords.ts

@@ -0,0 +1,84 @@
+/**
+ * Arrival binds a record `inputRest` as keywords only and drops the positional
+ * `input`. A verb that takes both declares an `sz.dynamic` rest and splits it
+ * here: the first keyword ends the positionals, and each keyword decodes by
+ * its own schema, so a default or an optional behaves as in a record rest.
+ */
+import { ASymbol } from "@here.build/arrival/reflect-internals";
+import { z } from "zod";
+
+export type KeywordShape = Readonly<Record<string, z.ZodType>>;
+
+export type Keywords<S extends KeywordShape> = {
+  readonly [K in keyof S]: z.output<S[K]>;
+};
+
+export function isKeyword(value: unknown): boolean {
+  return value instanceof ASymbol && String(value).startsWith(":");
+}
+
+export function splitKeywords<S extends KeywordShape>(
+  verb: string,
+  args: readonly unknown[],
+  shape: S,
+): { readonly positionals: readonly unknown[]; readonly keywords: Keywords<S> } {
+  const cut = args.findIndex((arg) => isKeyword(arg));
+  const positionals = cut === -1 ? [...args] : args.slice(0, cut);
+  while (positionals.length > 0 && positionals.at(-1) === undefined) positionals.pop();
+  const tail = cut === -1 ? [] : args.slice(cut).filter((arg) => arg !== undefined);
+  if (tail.length % 2 !== 0) throw new Error(`${verb}: dangling keyword ${String(tail.at(-1))}`);
+  const raw = new Map<string, unknown>();
+  for (let i = 0; i < tail.length; i += 2) {
+    const key = tail[i];
+    if (!isKeyword(key)) throw new Error(`${verb}: expected a keyword, got ${String(key)}`);
+    const name = String(key).slice(1);
+    if (!Object.hasOwn(shape, name)) {
+      const known = Object.keys(shape).map((field) => `:${field}`);
+      throw new Error(`${verb}: unknown keyword :${name}${known.length > 0 ? ` (known: ${known.join(", ")})` : ""}`);
+    }
+    if (raw.has(name)) throw new Error(`${verb}: keyword :${name} given twice`);
+    raw.set(name, tail[i + 1]);
+  }
+  const keywords: Record<string, unknown> = {};
+  for (const [name, schema] of Object.entries(shape)) {
+    try {
+      keywords[name] = schema.decode(raw.get(name));
+    } catch (error) {
+      const text =
+        error instanceof z.ZodError
+          ? error.issues.map((issue) => issue.message).join("; ")
+          : error instanceof Error
+            ? error.message
+            : String(error);
+      throw new Error(`${verb}: :${name} — ${text}`, { cause: error });
+    }
+  }
+  return { positionals, keywords: keywords as Keywords<S> };
+}
+
+/**
+ * The rest after a verb's fixed positionals. `:k v` pairs, or one trailing
+ * dict — the catalog teaches the dict form, and `String(dict)` is
+ * "[object Object]", which is how a rejected dict used to surface.
+ */
+export function keywordsOf<S extends KeywordShape>(verb: string, rest: readonly unknown[], shape: S): Keywords<S> {
+  if (rest.length === 1 && isPlainRecord(rest[0]) && !isKeyword(rest[0])) {
+    return keywordsOf(verb, recordKeywords(rest[0]), shape);
+  }
+  const { positionals, keywords } = splitKeywords(verb, rest, shape);
+  if (positionals.length > 0) throw new Error(`${verb}: unexpected argument ${String(positionals[0])}`);
+  return keywords;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function recordKeywords(record: Record<string, unknown>): unknown[] {
+  const pairs: unknown[] = [];
+  for (const [name, value] of Object.entries(record)) {
+    if (value === undefined) continue;
+    pairs.push(new ASymbol(`:${name}`), value);
+  }
+  return pairs;
+}

package/src/limits.ts

@@ -0,0 +1,13 @@
+/**
+ * scheme_repl / scheme_watch bounds. Time and inner-call budgets are
+ * opt-in: omit `timeoutMs` / `maxInternalCalls` for no limit. Eval-turn
+ * uses the same contract — no host ceiling.
+ */
+export interface SchemeReplLimits {
+  /** Binary content blocks kept from one inner tool result. */
+  readonly maxAttachments: number;
+}
+
+export const DEFAULT_SCHEME_REPL_LIMITS: SchemeReplLimits = Object.freeze({
+  maxAttachments: 4,
+});

package/src/program-source.ts

@@ -0,0 +1 @@
+export { programSourceLoader } from "@inhuman.tools/scheme-program/fs";

package/src/replay.ts

@@ -0,0 +1,46 @@
+/**
+ * Rebuild one program's trace from the children on the job. The daemon does
+ * not serve a graph: the same verbs run here, and a crossing reads the child
+ * it stamped instead of admitting a new one.
+ */
+import type { EvalTrace } from "@here.build/arrival/provenance";
+import { ProgrammaticJob, SCHEME_WATCH_TOOL_NAME } from "@inhuman.tools/harness-model";
+import { replayEvaluation } from "@inhuman.tools/scheme-program";
+import { watchHost } from "@inhuman.tools/scheme-watch";
+import type { BoundTool } from "@inhuman.tools/substrate/bound-tool";
+import { DoorSession } from "@inhuman.tools/substrate/doors";
+
+import { programHostOf, type SchemeReplHost } from "./env.js";
+
+function toolsFrom(job: ProgrammaticJob): Map<string, BoundTool> {
+  const tools = new Map<string, BoundTool>();
+  for (const name of Object.keys(job.boundTools)) {
+    if (name === "") continue;
+    tools.set(name, {
+      qualifiedName: name,
+      slug: "",
+      tool: name,
+      signature: () => ({ params: [], signatureText: name }),
+    });
+  }
+  return tools;
+}
+
+export async function replayScheme(job: ProgrammaticJob, trace: EvalTrace, signal: AbortSignal): Promise<void> {
+  const source = job.args?.source;
+  const host: SchemeReplHost = {
+    replayOnly: true,
+    replayTools: toolsFrom(job),
+    root: "",
+    doors: new DoorSession(() => {}),
+    signal,
+    evalProgram: typeof source === "string",
+    admit() {
+      throw new Error("replay does not admit");
+    },
+    observe: (run) => run(trace),
+  };
+  const program = programHostOf(host);
+  const watching = job.toolName === SCHEME_WATCH_TOOL_NAME ? watchHost(program) : program;
+  await replayEvaluation(job, watching, trace);
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.