@agentshouse/kit 0.0.1 → 0.1.0-alpha.2

package/src/peer.js

@@ -0,0 +1,124 @@
+import { connect } from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+import { readFrames, writeFrame } from "./channel.js";
+import { BRIDGE_RECONNECT_MAX_MS, BRIDGE_RECONNECT_MS } from "./contract.js";
+import { KitRefusal } from "./refusal.js";
+
+function connected(path) {
+  return new Promise((resolve, reject) => {
+    const socket = connect(path);
+    socket.once("connect", () => resolve(socket));
+    socket.once("error", reject);
+  });
+}
+
+export function bridgePeer(options) {
+  const outbound = [];
+  const drains = [];
+  let socket = null;
+  let ready = false;
+  let ended = false;
+  let greeting = null;
+  let refuse;
+  const refused = new Promise((_, reject) => {
+    refuse = reject;
+  });
+
+  function flush() {
+    while (ready && socket !== null && outbound.length > 0) {
+      if (socket.destroyed || socket.writableEnded) {
+        socket = null;
+        return;
+      }
+      options.onSend?.(outbound[0]);
+      writeFrame(socket, outbound[0]);
+      outbound.shift();
+    }
+    if (outbound.length === 0) for (const settle of drains.splice(0)) settle();
+  }
+
+  function received(frame) {
+    if (greeting === null) {
+      options.onFrame?.(frame);
+      return;
+    }
+    const settle = greeting;
+    greeting = null;
+    settle(frame);
+  }
+
+  async function attach(first) {
+    let backoff = BRIDGE_RECONNECT_MS;
+    const retry = async () => {
+      if (first) throw new KitRefusal("kit_bridge_unavailable", options.socket);
+      await delay(backoff);
+      backoff = Math.min(backoff * 2, BRIDGE_RECONNECT_MAX_MS);
+    };
+    while (!ended) {
+      let opened;
+      try {
+        opened = await connected(options.socket);
+      } catch {
+        await retry();
+        continue;
+      }
+      socket = opened;
+      ready = false;
+      opened.on("error", () => opened.destroy());
+      const answer = new Promise((resolve) => {
+        greeting = resolve;
+      });
+      const departure = new Promise((resolve) => opened.once("close", () => resolve(null)));
+      readFrames(opened, { onFrame: received, onRefusal: () => opened.destroy() });
+      writeFrame(opened, {
+        type: "hello",
+        role: options.role,
+        nonce: options.nonce,
+        ...options.hello(),
+      });
+      const greeted = await Promise.race([answer, departure]);
+      if (greeted === null) {
+        greeting = null;
+        socket = null;
+        await retry();
+        continue;
+      }
+      if (!options.greeted(greeted)) {
+        ended = true;
+        socket = null;
+        opened.destroy();
+        throw new KitRefusal("kit_bridge_refused", typeof greeted.code === "string" ? greeted.code : null);
+      }
+      ready = true;
+      flush();
+      void keep(opened).catch(refuse);
+      return greeted;
+    }
+    return null;
+  }
+
+  async function keep(current) {
+    if (!current.destroyed) await new Promise((resolve) => current.once("close", resolve));
+    if (socket === current) socket = null;
+    ready = false;
+    if (ended) return;
+    await attach(false);
+  }
+
+  return {
+    refused,
+    open: () => attach(options.retryInitial !== true),
+    send(frame) {
+      outbound.push(frame);
+      flush();
+    },
+    drained: () => outbound.length === 0 ? Promise.resolve() : new Promise((resolve) => drains.push(resolve)),
+    end() {
+      ended = true;
+      const current = socket;
+      socket = null;
+      if (current === null || current.destroyed || current.writableEnded) return Promise.resolve();
+      return new Promise((resolve) => current.end(resolve));
+    },
+  };
+}

package/src/plan.js

@@ -0,0 +1,57 @@
+const PLAN_INTERVAL_MS = 500;
+
+function steps(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  return entries.map((entry) => ({ label: entry.content, status: entry.status }));
+}
+
+export function observedPlans(options) {
+  const intervalMs = options.intervalMs ?? PLAN_INTERVAL_MS;
+  const now = options.now ?? (() => Date.now());
+  let timer = null;
+  let sentAt = null;
+  let sent = null;
+  let latest = null;
+  let completed = false;
+
+  function write(terminal) {
+    if (latest === null) return;
+    const serialized = JSON.stringify(latest);
+    if (!terminal && serialized === sent) return;
+    sent = serialized;
+    sentAt = now();
+    options.send({ steps: latest, terminal });
+  }
+
+  function cancel() {
+    if (timer === null) return;
+    clearTimeout(timer);
+    timer = null;
+  }
+
+  return {
+    observe(entries) {
+      if (completed) return;
+      const observed = steps(entries);
+      if (observed === null) return;
+      latest = observed;
+      if (timer !== null) return;
+      const wait = sentAt === null ? 0 : sentAt + intervalMs - now();
+      if (wait <= 0) {
+        write(false);
+        return;
+      }
+      timer = setTimeout(() => {
+        timer = null;
+        write(false);
+      }, wait);
+      timer.unref?.();
+    },
+    complete() {
+      if (completed) return;
+      completed = true;
+      cancel();
+      write(true);
+    },
+  };
+}

package/src/question.js

@@ -0,0 +1,316 @@
+import {
+  ELICITATION_FORM_MODE,
+  ELICITATION_FREE_TEXT_META,
+  ELICITATION_SECRET_META,
+  ELICITATION_URL_MODE,
+  SECRET_CEREMONY_STEPS_MAX,
+  SECRET_STEP_LABEL_MAX,
+  SECRET_STEP_TEXT_MAX,
+  NATIVE_CODEX_META,
+  NATIVE_CUSTOM_ANSWER_META,
+  NATIVE_OTHER_OPTION,
+  NATIVE_USER_NOTE_ROLE,
+  INTERACTION_OPTIONS_MAX,
+  INTERACTION_PROPERTY_MAX,
+} from "./contract.js";
+
+function declared(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+
+function withoutNativeMeta(value) {
+  if (Array.isArray(value)) return value.map(withoutNativeMeta);
+  const plain = declared(value);
+  if (plain === null) return value;
+  return Object.fromEntries(
+    Object.entries(plain)
+      .filter(([key]) => key !== "_meta")
+      .map(([key, nested]) => [key, withoutNativeMeta(nested)]),
+  );
+}
+
+function nativeCompanion(declaration) {
+  const meta = declared(declaration?._meta);
+  if (meta === null) return null;
+  const custom = declared(meta[NATIVE_CUSTOM_ANSWER_META]);
+  if (typeof custom?.questionId === "string") {
+    return { question: custom.questionId, other: null };
+  }
+  const codex = declared(meta[NATIVE_CODEX_META]);
+  if (codex?.role === NATIVE_USER_NOTE_ROLE && typeof codex.questionId === "string") {
+    return { question: codex.questionId, other: NATIVE_OTHER_OPTION };
+  }
+  return null;
+}
+
+function nativeSecret(declaration) {
+  return declared(declaration?._meta)?.[NATIVE_CODEX_META]?.isSecret === true;
+}
+
+function choiceHolder(declaration) {
+  return declaration?.type === "array" ? declared(declaration.items) : declared(declaration);
+}
+
+function choiceValues(declaration) {
+  const holder = choiceHolder(declaration);
+  const titled = holder?.oneOf ?? holder?.anyOf;
+  if (Array.isArray(titled)) {
+    return titled.map((option) => option?.const).filter((value) => typeof value === "string");
+  }
+  if (Array.isArray(holder?.enum)) {
+    return holder.enum.filter((value) => typeof value === "string");
+  }
+  return [];
+}
+
+function withoutChoice(holder, dropped) {
+  if (Array.isArray(holder.oneOf)) {
+    return { ...holder, oneOf: holder.oneOf.filter((option) => option?.const !== dropped) };
+  }
+  if (Array.isArray(holder.anyOf)) {
+    return { ...holder, anyOf: holder.anyOf.filter((option) => option?.const !== dropped) };
+  }
+  if (Array.isArray(holder.enum)) {
+    return { ...holder, enum: holder.enum.filter((value) => value !== dropped) };
+  }
+  return holder;
+}
+
+function withoutOtherChoice(declaration, dropped) {
+  const holder = choiceHolder(declaration);
+  if (dropped === null || holder === null) return declaration;
+  if (declaration.type === "array") {
+    return { ...declaration, items: withoutChoice(holder, dropped) };
+  }
+  return withoutChoice(holder, dropped);
+}
+
+function forwarded(declaration, name, marked) {
+  const plain = declared(declaration);
+  if (plain === null) return declaration;
+  const titled =
+    typeof plain.title === "string" && plain.title !== "" ? plain : { ...plain, title: name };
+  return marked ? { ...titled, _meta: { [ELICITATION_FREE_TEXT_META]: true } } : titled;
+}
+
+function foldedConventions(properties) {
+  const companions = new Map();
+  const conventions = new Map();
+  for (const [name, declaration] of Object.entries(properties)) {
+    const companion = nativeCompanion(declaration);
+    if (companion === null || !Object.hasOwn(properties, companion.question)) continue;
+    companions.set(name, companion.question);
+    conventions.set(companion.question, {
+      companion: name,
+      other: companion.other,
+      options: choiceValues(withoutOtherChoice(properties[companion.question], companion.other)),
+    });
+  }
+  return { companions, conventions };
+}
+
+function bounded(text, limit, fallback) {
+  const said = typeof text === "string" ? text.trim() : "";
+  return said === "" ? fallback : said.slice(0, limit);
+}
+
+const VISIT_LABEL = "Open the provider flow";
+const COLLECT_LABEL = "Paste what it gives you";
+
+export function elicitedVisit(params, correlation) {
+  if (params?.mode !== ELICITATION_URL_MODE || typeof params.url !== "string") return null;
+  let opened;
+  try {
+    opened = new URL(params.url);
+  } catch {
+    return null;
+  }
+  if (opened.protocol !== "https:") return null;
+  return {
+    form: {
+      correlation: correlation.correlation,
+      provider_turn: correlation.providerTurn,
+      message: bounded(params.message, SECRET_STEP_TEXT_MAX, VISIT_LABEL),
+      requested_schema: {
+        type: "object",
+        properties: {
+          visited: { type: "boolean", title: bounded(params.message, 200, VISIT_LABEL) },
+        },
+      },
+      _meta: { [ELICITATION_SECRET_META]: true },
+    },
+    ceremony: {
+      steps: [
+        {
+          kind: "visit",
+          label: bounded(params.message, SECRET_STEP_LABEL_MAX, VISIT_LABEL),
+          url: params.url,
+        },
+      ],
+    },
+    convention: {},
+  };
+}
+
+function secretCeremony(message, properties) {
+  const steps = [];
+  const shown = bounded(message, SECRET_STEP_TEXT_MAX, "");
+  if (shown !== "") steps.push({ kind: "show", label: "What the Agent is asking", text: shown });
+  for (const [name, declaration] of Object.entries(properties)) {
+    if (steps.length >= SECRET_CEREMONY_STEPS_MAX) break;
+    const property = declared(declaration);
+    steps.push({
+      kind: "collect",
+      label: bounded(property?.title, SECRET_STEP_LABEL_MAX, COLLECT_LABEL),
+      name,
+      ...(typeof property?.description === "string" && property.description !== ""
+        ? { description: property.description.slice(0, SECRET_STEP_TEXT_MAX) }
+        : {}),
+    });
+  }
+  return steps.length === 0 ? null : { steps };
+}
+
+export function elicitedForm(params, correlation) {
+  if (params?.mode !== ELICITATION_FORM_MODE) return null;
+  const schema = declared(params.requestedSchema);
+  if (schema === null) return null;
+  const properties = declared(schema.properties) ?? {};
+  const { companions, conventions } = foldedConventions(properties);
+  const carried = {};
+  for (const [name, declaration] of Object.entries(properties)) {
+    if (companions.has(name)) continue;
+    const convention = conventions.get(name);
+    const listed =
+      convention === undefined ? declaration : withoutOtherChoice(declaration, convention.other);
+    carried[name] = forwarded(withoutNativeMeta(listed), name, convention !== undefined);
+  }
+  const { _meta: _schemaMeta, properties: _properties, required, ...rest } = schema;
+  const secret = Object.values(properties).some(nativeSecret);
+  const ceremony = secret ? secretCeremony(params.message, carried) : null;
+  if (secret && ceremony === null) return null;
+  return {
+    ...(ceremony === null ? {} : { ceremony }),
+    form: {
+      correlation: correlation.correlation,
+      provider_turn: correlation.providerTurn,
+      message: typeof params.message === "string" ? params.message : "",
+      requested_schema: {
+        ...withoutNativeMeta(rest),
+        properties: carried,
+        ...(Array.isArray(required)
+          ? { required: required.filter((name) => !companions.has(name)) }
+          : {}),
+      },
+      ...(secret ? { _meta: { [ELICITATION_SECRET_META]: true } } : {}),
+    },
+    convention: Object.fromEntries(conventions),
+  };
+}
+
+function nativeAnswer(content, name, convention, value) {
+  if (Array.isArray(value)) {
+    content[name] = value.filter((item) => convention.options.includes(item));
+    const typed = value.filter((item) => !convention.options.includes(item));
+    if (typed.length > 0) content[convention.companion] = typed.join(", ");
+    return;
+  }
+  if (typeof value !== "string" || convention.options.includes(value)) {
+    content[name] = value;
+    return;
+  }
+  content[convention.companion] = value;
+  if (convention.other !== null) content[name] = convention.other;
+}
+
+export function elicitationResponse(convention, response) {
+  if (response?.action !== "accept") return { action: "decline" };
+  const content = {};
+  for (const [name, value] of Object.entries(response.content)) {
+    const native = convention[name];
+    if (native === undefined) content[name] = value;
+    else nativeAnswer(content, name, native, value);
+  }
+  return { action: "accept", content };
+}
+
+function grokOption(option) {
+  if (typeof option?.label !== "string" || option.label.length === 0) return null;
+  return {
+    const: option.label,
+    title: option.label,
+    ...(typeof option.description === "string" && option.description.length > 0
+      ? { description: option.description }
+      : {}),
+  };
+}
+
+export function grokForm(params, correlation) {
+  if (params?.mode !== "default" && params?.mode !== "plan") return null;
+  if (
+    !Array.isArray(params.questions) ||
+    params.questions.length === 0 ||
+    params.questions.length > INTERACTION_PROPERTY_MAX
+  ) {
+    return null;
+  }
+  const properties = {};
+  const questions = {};
+  const named = new Set();
+  for (const [position, question] of params.questions.entries()) {
+    if (
+      typeof question?.question !== "string" ||
+      question.question.length === 0 ||
+      named.has(question.question) ||
+      !Array.isArray(question.options) ||
+      question.options.length > INTERACTION_OPTIONS_MAX
+    ) {
+      return null;
+    }
+    const options = question.options.map(grokOption);
+    if (options.some((option) => option === null)) return null;
+    const labels = options.map((option) => option.const);
+    if (new Set(labels).size !== labels.length) return null;
+    const name = `question_${position}`;
+    const choices = options.length === 0 ? {} : { oneOf: options };
+    properties[name] =
+      question.multiSelect === true
+        ? {
+            type: "array",
+            title: question.question,
+            items: { type: "string", ...choices },
+            uniqueItems: true,
+          }
+        : { type: "string", title: question.question, ...choices };
+    questions[name] = question.question;
+    named.add(question.question);
+  }
+  return {
+    form: {
+      correlation: correlation.correlation,
+      provider_turn: correlation.providerTurn,
+      message: `Grok Build needs your input before it continues${params.mode === "plan" ? " its plan" : ""}.`,
+      requested_schema: {
+        type: "object",
+        properties,
+        required: Object.keys(properties),
+      },
+    },
+    convention: questions,
+  };
+}
+
+export function grokResponse(convention, response) {
+  if (response?.action !== "accept") return { outcome: "cancelled" };
+  const answers = {};
+  for (const [name, question] of Object.entries(convention)) {
+    const value = response.content?.[name];
+    if (typeof value === "string") answers[question] = [value];
+    else if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+      answers[question] = value;
+    } else {
+      return { outcome: "cancelled" };
+    }
+  }
+  return { outcome: "accepted", answers };
+}

package/src/refusal.js

@@ -0,0 +1,79 @@
+export class KitRefusal extends Error {
+  constructor(code, detail = null) {
+    super(detail === null ? code : `${code}: ${detail}`);
+    this.code = code;
+  }
+}
+
+export class EpochReportRequired extends Error {
+  constructor(epoch) {
+    super(`epoch_report_required: ${epoch}`);
+    this.code = "epoch_report_required";
+  }
+}
+
+export class HousePending extends Error {
+  constructor(pending) {
+    super("pending");
+    this.pending = pending;
+    this.retryAfterSeconds = pending.retry_after;
+  }
+}
+
+function typedCode(answer) {
+  const code = answer?.error?.code;
+  return typeof code === "string" && code !== "" ? code : null;
+}
+
+export function houseRefusal(status, answer, path = null) {
+  const code = typedCode(answer);
+  if (status >= 500 && code === null) return new KitRefusal("kit_house_unavailable", path);
+  if (status === 409 && code === "epoch_report_required") {
+    return new EpochReportRequired(answer.error.log_epoch);
+  }
+  const refusal = new KitRefusal(code ?? `house_http_${status}`, answer?.error?.declaration ?? null);
+  refusal.status = status;
+  refusal.payload = answer;
+  return refusal;
+}
+
+export function housePending(answer) {
+  const pending = answer?.pending;
+  if (typeof pending !== "object" || pending === null || Array.isArray(pending)) return null;
+  if (!Number.isSafeInteger(pending.retry_after) || pending.retry_after < 1) return null;
+  return new HousePending(pending);
+}
+
+export function throwHouseAnswer(status, answer, path = null) {
+  if (status === 202) {
+    const pending = housePending(answer);
+    if (pending !== null) throw pending;
+    throw new KitRefusal("kit_house_unavailable", path);
+  }
+  if (status < 200 || status >= 300) throw houseRefusal(status, answer, path);
+}
+
+export function houseAnswered(error) {
+  return error instanceof KitRefusal && error.status !== undefined;
+}
+
+export function houseAnsweredFailure(error) {
+  return houseAnswered(error) && error.status >= 500;
+}
+
+export function houseFailed(error) {
+  return (
+    error instanceof HousePending ||
+    (houseAnsweredFailure(error) && error.payload.error.retryable === true) ||
+    (error instanceof KitRefusal && error.code === "kit_house_unavailable")
+  );
+}
+
+export function formatCommandError(error) {
+  if (!(error instanceof Error)) return "kit_command_failed";
+  if (error instanceof HousePending) return JSON.stringify({ pending: error.pending });
+  if (error instanceof KitRefusal && error.payload !== undefined) {
+    return `${error.message}\n${JSON.stringify(error.payload)}`;
+  }
+  return error.message;
+}