@agentshouse/kit 0.1.0-alpha.8 → 0.2.0

package/src/peer.js

@@ -1,124 +0,0 @@
-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

@@ -1,57 +0,0 @@
-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

@@ -1,316 +0,0 @@
-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

@@ -1,79 +0,0 @@
-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;
-}