@wenathlan/getry 2.0.165 → 2.0.167

package/gatewaycheck.ts

@@ -0,0 +1,142 @@
+/**
+ * gatewaycheck — consolidated gateway check lane of the getry family
+ * @module gatewaycheck
+ * @family wave/gatewaycheck
+ * One keyed file per family: the former variant arms (gatewayprobe, gatewaysmoke)
+ * retired into this seat with every behavior preserved under the same name.
+ */
+
+import { startgatewayfixtureserver } from "./test/gatewayserver.ts";
+import type { baseurlconfig } from "./types.ts";
+
+/**
+ * the offline smoke seat of the 1.1.83 family: it starts the localhost fixture
+ * server, loads the built gateway module and runs one full request cycle
+ * against the recorded openaicompat fixture offline — no provider endpoint,
+ * no key, no external network — so the container image proves the gateway
+ * call path before it ships.
+ */
+export async function gatewaysmokeseat(): Promise<void> {
+  const server = await startgatewayfixtureserver();
+  try {
+    /* the smoke loads the BUILT gateway module — build/llm.js is a container
+     * build artifact a fresh checkout never carries, so the specifier rides a
+     * variable (tsc never fails on the absent artifact while the runtime
+     * keeps loading the built face) and the cast pins the module to the
+     * source contract that sits beside it. */
+    const builtpath = "./build/llm.js";
+    const gateway = (await import(builtpath)) as typeof import("./llm.ts");
+    const config: baseurlconfig = {
+      providerid: "smoke",
+      kind: "openaicompat",
+      baseurl: `http://127.0.0.1:${server.port}/openaicompat`,
+      enabled: true,
+      consented: true,
+      consentedat: Date.now(),
+      updatedat: Date.now(),
+    };
+    const outcome = await gateway.gatewaycall({
+      config,
+      model: "fixture-model-a",
+      messages: [{ role: "user", content: "draft one step" }],
+      requestid: "smoke-1",
+      transport: async (url: string, init: { method: string; headers: Record<string, string>; body?: string }) => {
+        const response = await fetch(url, { method: init.method, headers: init.headers, body: init.body });
+        return {
+          status: response.status,
+          headers: Object.fromEntries(response.headers.entries()),
+          body: await response.text(),
+        };
+      },
+    });
+    if (!outcome.text.includes("goal")) throw new Error("The gateway smoke answer carries no goal field.");
+    if (outcome.usage?.totaltokens !== 55) throw new Error("The gateway smoke usage did not parse.");
+    const streamed = await gateway.gatewaystream({
+      config: { ...config, providerid: "smoke-stream" },
+      model: "fixture-model-a",
+      messages: [{ role: "user", content: "stream" }],
+      transport: async (url: string, init: { method: string; headers: Record<string, string>; body?: string }) => {
+        const response = await fetch(url, { method: init.method, headers: init.headers, body: init.body });
+        return {
+          status: response.status,
+          headers: Object.fromEntries(response.headers.entries()),
+          body: await response.text(),
+        };
+      },
+    });
+    if (streamed.tokens.length !== 3)
+      throw new Error("The gateway smoke stream did not carry the three recorded deltas.");
+    console.log(
+      JSON.stringify({
+        valid: true,
+        requestid: outcome.requestid,
+        tokens: streamed.tokens.length,
+        usage: outcome.usage.totaltokens,
+      }),
+    );
+  } finally {
+    await server.close();
+  }
+}
+
+/**
+ * the live probe seat: a manual chat round trip against a deployed DevThink
+ * gateway (the ZAI sandbox deploy of the getry template). this seat is NOT
+ * wired into the deterministic gates: it needs the live network and the
+ * deployed host is a runtime setting, never a tracked constant of a gate.
+ * it exercises the exact surface the Sol chat client consumes: GET
+ * /v1/models (the picker) and POST /v1/chat/completions with the model
+ * "devthink" (content + reasoning_content on the answer turn).
+ */
+export async function gatewayprobeseat(base: string): Promise<void> {
+  /* GET /v1/models — the chat picker surface. */
+  const models = await fetch(`${base}/v1/models`);
+  if (!models.ok) {
+    console.error(`models probe failed: ${models.status}`);
+    process.exit(1);
+  }
+  const modellist = (await models.json()) as { data?: Array<{ id?: string }> };
+  const ids = (modellist.data ?? []).map((m) => m.id);
+  console.log(`models: ${ids.join(", ") || "(none)"}`);
+
+  /* POST /v1/chat/completions — one round trip on the chat surface. */
+  const chat = await fetch(`${base}/v1/chat/completions`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      model: "devthink",
+      messages: [{ role: "user", content: "Reply with exactly: gateway ok" }],
+      max_tokens: 20,
+    }),
+  });
+  if (!chat.ok) {
+    console.error(`chat probe failed: ${chat.status}`);
+    process.exit(1);
+  }
+  const answer = (await chat.json()) as {
+    choices?: Array<{ message?: { content?: string; reasoning_content?: string } }>;
+    usage?: unknown;
+  };
+  const turn = answer.choices?.[0]?.message;
+  console.log(`chat: ${JSON.stringify(turn?.content ?? "")}`);
+  console.log(`reasoning present: ${Boolean(turn?.reasoning_content)}`);
+  console.log(`usage: ${JSON.stringify(answer.usage ?? {})}`);
+
+  if (turn?.content !== "gateway ok") {
+    console.error("the gateway answered, but the round trip content drifted");
+    process.exit(1);
+  }
+  console.log("gateway probe: ok");
+}
+
+/* the dispatched entry the two seats ride: an http(s) URL argument answers
+ * the live probe seat (`node gatewaycheck.ts https://<deployed-gateway-host>`,
+ * the documented probe call), every other call answers the offline smoke
+ * seat (`node gatewaycheck.ts`, the container call). */
+const firstarg = (process.argv[2] ?? "").replace(/\/+$/, "");
+
+if (/^https?:\/\//.test(firstarg)) {
+  await gatewayprobeseat(firstarg);
+} else {
+  await gatewaysmokeseat();
+}

package/intelligence.ts

@@ -0,0 +1,169 @@
+/**
+ * intelligence.ts — the AI planning, provenance, retrieval and metrics
+ * domain of the devthink family (the saddle ownership law, wave a,
+ * actions 108-112: the intelligence domain moved out of the saddle
+ * engine — the master virtualization engine keeps only the
+ * virtualization modalities, and every workload feature that is not
+ * sandbox/vm/runner/vgpu/vcpu/ports/hardware-virtual rides its new
+ * owner; devthink answers the intelligence lane).
+ *
+ * This file is the v2.0.0 grand-merge consolidation of the former nested
+ * folders of the repository (ai) into the single
+ * root-level domain file: one optimized TypeScript file per correlated
+ * domain, ordinal sections, JSDoc on every block, intra-domain imports
+ * dissolved. Every capability of every source file is preserved here;
+ * the pure re-export barrels (none in this domain) folded their surface
+ * into this file directly. Zero runtime imports: the domain stays
+ * browser-pure (the crypto.subtle digest the rag manifest hashes ride
+ * degrades to the deterministic byte fallback under hosts without it).
+ */
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 1: ai/provenance.ts — context provenance links retrieved chunks to source, query and transformation metadata. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * context provenance links retrieved chunks to source, query and transformation metadata.
+ */
+
+/** one retrieved chunk a provenance record carries (the loose input form:
+ * every field answers a sensible default the record normalizes). */
+export interface provenancechunkinput {
+  id?: string | number;
+  contenthash?: string;
+  score?: number;
+  headingpath?: string;
+  tokencount?: number;
+  citation?: string;
+}
+
+/** the provenance call shape: a source or a source url names the record,
+ * the chunks and the metadata ride beside them. */
+export interface provenanceinput {
+  source?: string;
+  sourceurl?: string;
+  documentid?: string;
+  query?: string;
+  retrievedat?: number;
+  chunks?: provenancechunkinput[];
+  metadata?: Record<string, unknown>;
+}
+
+/** the serializable retrieval record provenance answers (the normalized
+ * form the merge lane and the context readers consume). */
+export interface provenancerecord {
+  version: number;
+  source: string;
+  sourceurl?: string;
+  documentid?: string;
+  query?: string;
+  retrievedat: number;
+  chunks: Array<{ id: string; contenthash?: string; score?: number; headingpath?: string; tokencount?: number; citation?: string }>;
+  metadata: Record<string, unknown>;
+}
+
+/** Creates a serializable retrieval record for an agent context result. */
+export function provenance(input: provenanceinput = {}) {
+  if (!input.source && !input.sourceurl) throw new TypeError("provenance requires a source");
+  return { version: 1, source: (input.source ?? input.sourceurl) as string, sourceurl: input.sourceurl, documentid: input.documentid, query: input.query, retrievedat: Number(input.retrievedat ?? Date.now()), chunks: Array.isArray(input.chunks) ? input.chunks.map((chunk: any, index: any) => ({ id: String(chunk.id ?? index), contenthash: chunk.contenthash, score: chunk.score === undefined ? undefined : Number(chunk.score), headingpath: chunk.headingpath, tokencount: chunk.tokencount, citation: chunk.citation ?? input.sourceurl })) : [], metadata: { ...(input.metadata ?? {}) } } satisfies provenancerecord;
+}
+
+/** Merges provenance records while deduplicating chunk identifiers. */
+export function mergeprovenance(records: provenancerecord[] = []) {
+  const valid = records.filter(Boolean);
+  const chunks: any[] = [];
+  const seen = new Set();
+  for (const record of valid) for (const chunk of record.chunks ?? []) { const key = `${record.documentid ?? record.source}:${chunk.id}`; if (seen.has(key)) continue; seen.add(key); chunks.push({ ...chunk, source: record.source, documentid: record.documentid }); }
+  return { version: 1, sources: [...new Set(valid.map((record: any) => record.source))], chunks, mergedat: Date.now() };
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 2: ai/tokens.ts — token helpers use configurable model ratios and never require a provider tokenizer. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * token helpers use configurable model ratios and never require a provider tokenizer.
+ */
+const ratios = Object.freeze({ default: 4, gpt: 3.5, claude: 3.2, gemini: 3.5 });
+
+export function estimatetokens(text: any, model = "default") { const ratio = (ratios as Record<string, number>)[model] ?? ratios.default; return Math.ceil(String(text ?? "").length / ratio); }
+export function fitscontext(text: any, context: any, model = "default") { return estimatetokens(text, model) <= context; }
+export function tokenbudget(text: any, options: Record<string, any> = {}) { const tokens = estimatetokens(text, options.model); return { tokens, context: options.context ?? null, fits: options.context == null ? true : tokens <= options.context, remaining: options.context == null ? null : Math.max(0, options.context - tokens) }; }
+export function settokenratios(values: Record<string, any> = {}) { Object.assign(ratios, values); return { ...ratios }; }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 3: ai/chunk.ts — markdown chunking preserves heading paths and uses paragraph boundaries before hard cuts. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * markdown chunking preserves heading paths and uses paragraph boundaries before hard cuts.
+ */
+
+export function chunkmarkdown(markdown: any, options: Record<string, any> = {}) {
+  const maxtokens = options.maxtokens ?? 512;
+  const overlap = options.overlaptokens ?? 50;
+  const lines = String(markdown ?? "").split(/\r?\n/);
+  const chunks: any[] = [];
+  let headingpath: any[] = [];
+  let buffer: string[] = [];
+  function flush() { if (!buffer.length) return; const content = buffer.join("\n").trim(); if (content) chunks.push({ content, headingpath: [...headingpath], tokencount: estimatetokens(content, options.model) }); buffer = []; }
+  for (const line of lines) {
+    const heading = line.match(/^(#{1,6})[ \t]+(\S.*)$/);
+    if (heading) { flush(); const level = heading[1].length; headingpath = headingpath.slice(0, level - 1); headingpath[level - 1] = heading[2].trim(); buffer.push(line); continue; }
+    buffer.push(line);
+    if (estimatetokens(buffer.join("\n"), options.model) > maxtokens) { const last: any = buffer.pop(); flush(); const overlaptext = buffer.slice(-overlap).join("\n"); buffer = overlaptext ? [overlaptext, last] : [last]; }
+  }
+  flush();
+  return chunks.map((chunk: any, index: any) => ({ ...chunk, id: `chunk${index}` }));
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 4: ai/rag.ts — rag manifests connect chunks to embedding stores without forcing a vendor client. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * rag manifests connect chunks to embedding stores without forcing a vendor client.
+ */
+export async function ragmanifest(input: Record<string, any> = {}) {
+  const chunks = input.chunks ?? [];
+  const unique = [];
+  const hashes = new Set();
+  for (const chunk of chunks) { const hash = await hashtext(chunk.content); if (hashes.has(hash)) continue; hashes.add(hash); unique.push({ ...chunk, contenthash: hash, documentid: hash.slice(0, 16), metadata: { ...(input.metadata ?? {}), ...(chunk.metadata ?? {}) } }); }
+  return { documentid: (await hashtext(input.source ?? unique.map((chunk: any) => chunk.content).join("\n"))).slice(0, 16), source: input.source, chunks: unique, embeddingmodel: input.embeddingmodel, embeddingdimensions: input.embeddingdimensions, createdat: Date.now() };
+}
+
+export function vectorrecord(chunk: any, vector: any, options: Record<string, any> = {}) { return { id: `${chunk.documentid}-${chunk.id}`, vector, metadata: { headingpath: chunk.headingpath, contenthash: chunk.contenthash, sourceurl: options.sourceurl, tokencount: chunk.tokencount, contenttype: options.contenttype ?? "text", language: options.language ?? "en", embeddingmodel: options.embeddingmodel, embeddingdimensions: vector?.length } }; }
+
+async function hashtext(text: any) { const bytes = new TextEncoder().encode(String(text)); if (globalThis.crypto?.subtle) { const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes); return [...new Uint8Array(digest)].map((value: any) => value.toString(16).padStart(2, "0")).join(""); } return Array.from(bytes).map((value: any) => value.toString(16).padStart(2, "0")).join("").slice(0, 64).padEnd(64, "0"); }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 5: ai/llmstxt.ts — llms text generation creates compact absolute links for agent consumption. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * llms text generation creates compact absolute links for agent consumption.
+ */
+export function llmstxt(options: Record<string, any> = {}) {
+  const title = options.title ?? "devthink";
+  const description = options.description ?? "the reasoning workspace of the devthink family";
+  const pages = (options.pages ?? []).filter((page: any) => page?.url && /^https:\/\//.test(page.url)).slice(0, options.limit ?? 100);
+  const lines = [`# ${title}`, `> ${description}`, "", "## pages", "", ...pages.map((page: any) => `- [${page.title ?? page.url}](${page.url}): ${(page.description ?? "").slice(0, 100)}`)];
+  return `${lines.join("\n")}\n`;
+}
+
+export function llmsfull(options: Record<string, any> = {}) { return (options.pages ?? []).filter((page: any) => page?.url && /^https:\/\//.test(page.url)).map((page: any) => `# ${page.title ?? page.url}\n\nsource: ${page.url}\n\n${page.content ?? ""}`).join("\n\n---\n\n"); }
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 6: ai/metrics.ts — metrics keeps low-cardinality counters and durations without requiring a telemetry vendor. */
+/* ════════════════════════════════════════════════════════════════════ */
+/**
+ * metrics keeps low-cardinality counters and durations without requiring a telemetry vendor.
+ */
+
+/** Creates an in-memory metric collector with bounded names and labels. */
+export function metricstore(options: Record<string, any> = {}) {
+  const maxnames = Number(options.maxnames ?? 256);
+  const values = new Map();
+  const durations = new Map();
+  function key(name: any, labels: Record<string, any> = {}) { const sorted = Object.entries(labels).slice(0, 8).sort(([left], [right]) => left.localeCompare(right)); return `${String(name)}|${JSON.stringify(sorted)}`; }
+  function count(name: any, amount = 1, labels: Record<string, any> = {}) { if (values.size >= maxnames && !values.has(key(name, labels))) throw new Error("metric cardinality limit reached"); const metric = key(name, labels); values.set(metric, (values.get(metric) ?? 0) + Number(amount)); return values.get(metric); }
+  function observe(name: any, milliseconds: any, labels: Record<string, any> = {}) { const metric = key(name, labels); const list = durations.get(metric) ?? []; if (list.length < 1000) list.push(Number(milliseconds)); durations.set(metric, list); return Number(milliseconds); }
+  function snapshot() { return { counters: Object.fromEntries(values), durations: Object.fromEntries([...durations].map(([name, list]) => [name, { count: list.length, total: list.reduce((sum: any, value: any) => sum + value, 0), max: Math.max(0, ...list) }])) }; }
+  function reset() { values.clear(); durations.clear(); }
+  return { count, observe, snapshot, reset };
+}