@opengeni/codemode 0.2.2

package/src/declarations.ts

@@ -0,0 +1,345 @@
+import type { AttemptToolCatalog, AttemptToolCatalogEntry } from "@opengeni/contracts";
+import { parseVerifiedAttemptToolCatalog } from "./index";
+
+export type GenerateCodemodeDeclarationsOptions = {
+  /** Package whose augmentable CodemodeGeneratedTools interface owns the namespace. */
+  moduleSpecifier?: string;
+};
+
+type NamespaceNode = {
+  children: Map<string, NamespaceNode>;
+  entry: AttemptToolCatalogEntry | null;
+};
+
+/**
+ * Generate declaration merging for one exact, digest-pinned attempt catalog.
+ * Types improve authoring only; runtime catalog validation remains authoritative.
+ */
+export function generateCodemodeDeclarations(
+  catalog: AttemptToolCatalog,
+  options: GenerateCodemodeDeclarationsOptions = {},
+): string {
+  const verified = parseVerifiedAttemptToolCatalog(catalog);
+  const moduleSpecifier = options.moduleSpecifier ?? "@opengeni/codemode";
+  const root = namespaceNode();
+  for (const entry of verified.entries) insertEntry(root, entry);
+
+  return [
+    "// Generated by @opengeni/codemode. Do not edit.",
+    `// Attempt catalog digest: ${verified.digest}`,
+    `import type { CodemodeCallOptions, CodemodeToolResult } from ${JSON.stringify(moduleSpecifier)};`,
+    "",
+    `declare module ${JSON.stringify(moduleSpecifier)} {`,
+    "  interface CodemodeGeneratedTools {",
+    ...renderChildren(root, 4),
+    "  }",
+    "}",
+    "",
+    "export {};",
+    "",
+  ].join("\n");
+}
+
+/** Honest JSON-Schema-to-TypeScript projection used by declaration generation. */
+export function jsonSchemaToTypeScript(schema: unknown): string {
+  return schemaType(schema, schema, new Set<string>(), 0);
+}
+
+function namespaceNode(): NamespaceNode {
+  return { children: new Map(), entry: null };
+}
+
+function insertEntry(root: NamespaceNode, entry: AttemptToolCatalogEntry): void {
+  let node = root;
+  for (const [index, segment] of entry.codemodePath.entries()) {
+    if (node.entry) {
+      throw new Error(
+        `Codemode declaration path ${entry.codemodePath.join(".")} extends a tool leaf`,
+      );
+    }
+    let child = node.children.get(segment);
+    if (!child) {
+      child = namespaceNode();
+      node.children.set(segment, child);
+    }
+    node = child;
+    if (index === entry.codemodePath.length - 1) {
+      if (node.entry || node.children.size > 0) {
+        throw new Error(`Codemode declaration path ${entry.codemodePath.join(".")} collides`);
+      }
+      node.entry = entry;
+    }
+  }
+}
+
+function renderChildren(node: NamespaceNode, indent: number): string[] {
+  const lines: string[] = [];
+  for (const [name, child] of [...node.children].sort(([left], [right]) =>
+    left.localeCompare(right),
+  )) {
+    if (child.entry) {
+      lines.push(...renderTool(name, child.entry, indent));
+      continue;
+    }
+    lines.push(`${spaces(indent)}readonly ${name}: {`);
+    lines.push(...renderChildren(child, indent + 2));
+    lines.push(`${spaces(indent)}};`);
+  }
+  return lines;
+}
+
+function renderTool(name: string, entry: AttemptToolCatalogEntry, indent: number): string[] {
+  const input = schemaType(entry.inputSchema, entry.inputSchema, new Set<string>(), 0);
+  const output = entry.outputSchema
+    ? schemaType(entry.outputSchema, entry.outputSchema, new Set<string>(), 0)
+    : "CodemodeToolResult";
+  const optionalArguments = rootObjectArgumentsAreOptional(entry.inputSchema);
+  const description = boundedDoc(entry.description ?? entry.title);
+  return [
+    ...(description ? renderDoc(description, indent) : []),
+    `${spaces(indent)}readonly ${name}: (`,
+    `${spaces(indent + 2)}argumentsValue${optionalArguments ? "?" : ""}: ${input},`,
+    `${spaces(indent + 2)}options?: CodemodeCallOptions,`,
+    `${spaces(indent)}) => Promise<${output}>;`,
+  ];
+}
+
+function rootObjectArgumentsAreOptional(schema: unknown): boolean {
+  if (!isSchemaObject(schema)) return false;
+  const required = Array.isArray(schema.required)
+    ? schema.required.filter((value): value is string => typeof value === "string")
+    : [];
+  return required.length === 0 && (schema.type === "object" || isSchemaObject(schema.properties));
+}
+
+function schemaType(
+  schema: unknown,
+  rootSchema: unknown,
+  resolvingRefs: Set<string>,
+  depth: number,
+): string {
+  if (depth > 48 || schema === true) return "unknown";
+  if (schema === false) return "never";
+  if (!isSchemaObject(schema)) return "unknown";
+
+  if (typeof schema.$ref === "string") {
+    const reference = schema.$ref;
+    if (!reference.startsWith("#/") || resolvingRefs.has(reference)) return "unknown";
+    const resolved = resolveLocalReference(rootSchema, reference);
+    if (resolved === undefined) return "unknown";
+    const next = new Set(resolvingRefs);
+    next.add(reference);
+    return schemaType(resolved, rootSchema, next, depth + 1);
+  }
+
+  if (Object.hasOwn(schema, "const")) return literalType(schema.const);
+  if (Array.isArray(schema.enum)) {
+    return union(schema.enum.map(literalType));
+  }
+
+  const composites: string[] = [];
+  if (Array.isArray(schema.oneOf)) {
+    composites.push(
+      union(schema.oneOf.map((part) => schemaType(part, rootSchema, resolvingRefs, depth + 1))),
+    );
+  }
+  if (Array.isArray(schema.anyOf)) {
+    composites.push(
+      union(schema.anyOf.map((part) => schemaType(part, rootSchema, resolvingRefs, depth + 1))),
+    );
+  }
+  if (Array.isArray(schema.allOf)) {
+    composites.push(
+      intersection(
+        schema.allOf.map((part) => schemaType(part, rootSchema, resolvingRefs, depth + 1)),
+      ),
+    );
+  }
+  if (composites.length > 0) {
+    const composed = intersection(composites);
+    return schema.nullable === true ? union([composed, "null"]) : composed;
+  }
+
+  const declaredTypes = Array.isArray(schema.type)
+    ? schema.type.filter((value): value is string => typeof value === "string")
+    : typeof schema.type === "string"
+      ? [schema.type]
+      : inferredSchemaTypes(schema);
+  const rendered = declaredTypes.map((type) =>
+    typeType(type, schema, rootSchema, resolvingRefs, depth + 1),
+  );
+  if (schema.nullable === true) rendered.push("null");
+  return union(rendered.length > 0 ? rendered : ["unknown"]);
+}
+
+function inferredSchemaTypes(schema: Record<string, unknown>): string[] {
+  if (isSchemaObject(schema.properties) || Object.hasOwn(schema, "additionalProperties")) {
+    return ["object"];
+  }
+  if (Object.hasOwn(schema, "items") || Array.isArray(schema.prefixItems)) return ["array"];
+  return [];
+}
+
+function typeType(
+  type: string,
+  schema: Record<string, unknown>,
+  rootSchema: unknown,
+  resolvingRefs: Set<string>,
+  depth: number,
+): string {
+  switch (type) {
+    case "null":
+      return "null";
+    case "boolean":
+      return "boolean";
+    case "integer":
+    case "number":
+      return "number";
+    case "string":
+      return "string";
+    case "array":
+      return arrayType(schema, rootSchema, resolvingRefs, depth);
+    case "object":
+      return objectType(schema, rootSchema, resolvingRefs, depth);
+    default:
+      return "unknown";
+  }
+}
+
+function arrayType(
+  schema: Record<string, unknown>,
+  rootSchema: unknown,
+  resolvingRefs: Set<string>,
+  depth: number,
+): string {
+  if (Array.isArray(schema.prefixItems)) {
+    const tuple = schema.prefixItems.map((item) =>
+      schemaType(item, rootSchema, resolvingRefs, depth + 1),
+    );
+    if (schema.items === false) return `readonly [${tuple.join(", ")}]`;
+    const rest =
+      schema.items === undefined || schema.items === true
+        ? "unknown"
+        : schemaType(schema.items, rootSchema, resolvingRefs, depth + 1);
+    return `readonly [${tuple.join(", ")}${tuple.length > 0 ? ", " : ""}...${rest}[]]`;
+  }
+  const item =
+    schema.items === undefined || schema.items === true
+      ? "unknown"
+      : schemaType(schema.items, rootSchema, resolvingRefs, depth + 1);
+  return `readonly (${item})[]`;
+}
+
+function objectType(
+  schema: Record<string, unknown>,
+  rootSchema: unknown,
+  resolvingRefs: Set<string>,
+  depth: number,
+): string {
+  const properties = isSchemaObject(schema.properties) ? schema.properties : {};
+  const required = new Set(
+    Array.isArray(schema.required)
+      ? schema.required.filter((value): value is string => typeof value === "string")
+      : [],
+  );
+  const entries = Object.entries(properties).sort(([left], [right]) => left.localeCompare(right));
+  const fields = entries.map(([name, propertySchema]) => {
+    const key = identifierOrQuoted(name);
+    const optional = required.has(name) ? "" : "?";
+    return `readonly ${key}${optional}: ${schemaType(
+      propertySchema,
+      rootSchema,
+      resolvingRefs,
+      depth + 1,
+    )}`;
+  });
+  for (const missing of [...required].filter((name) => !Object.hasOwn(properties, name)).sort()) {
+    fields.push(`readonly ${identifierOrQuoted(missing)}: unknown`);
+  }
+
+  const additional = schema.additionalProperties;
+  if (additional !== false) {
+    if (entries.length === 0 && additional !== undefined && additional !== true) {
+      return `Readonly<Record<string, ${schemaType(
+        additional,
+        rootSchema,
+        resolvingRefs,
+        depth + 1,
+      )}>>`;
+    }
+    // Known properties and typed additional properties can have incompatible
+    // value types. `unknown` preserves legal values without fabricating a lie.
+    fields.push("readonly [key: string]: unknown");
+  }
+  return fields.length === 0 ? "Record<string, never>" : `{ ${fields.join("; ")} }`;
+}
+
+function resolveLocalReference(rootSchema: unknown, reference: string): unknown {
+  let current = rootSchema;
+  for (const encoded of reference.slice(2).split("/")) {
+    if (!isSchemaObject(current)) return undefined;
+    const segment = encoded.replace(/~1/gu, "/").replace(/~0/gu, "~");
+    if (!Object.hasOwn(current, segment)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}
+
+function literalType(value: unknown): string {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `readonly [${value.map(literalType).join(", ")}]`;
+  if (isSchemaObject(value)) {
+    return `{ ${Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, child]) => `readonly ${identifierOrQuoted(key)}: ${literalType(child)}`)
+      .join("; ")} }`;
+  }
+  return "unknown";
+}
+
+function union(types: string[]): string {
+  const unique = [...new Set(types)];
+  if (unique.includes("unknown")) return "unknown";
+  if (unique.length === 0) return "never";
+  return unique.length === 1 ? unique[0]! : unique.map(parenthesizeComposite).join(" | ");
+}
+
+function intersection(types: string[]): string {
+  const unique = [...new Set(types.filter((type) => type !== "unknown"))];
+  if (unique.length === 0) return "unknown";
+  return unique.length === 1 ? unique[0]! : unique.map(parenthesizeComposite).join(" & ");
+}
+
+function parenthesizeComposite(type: string): string {
+  return /[|&]/u.test(type) ? `(${type})` : type;
+}
+
+function identifierOrQuoted(value: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(value) ? value : JSON.stringify(value);
+}
+
+function boundedDoc(value: string | undefined): string | null {
+  if (!value) return null;
+  const normalized = value.replace(/\s+/gu, " ").trim().replace(/\*\//gu, "*\\/");
+  if (!normalized) return null;
+  return normalized.length <= 512 ? normalized : `${normalized.slice(0, 509)}...`;
+}
+
+function renderDoc(value: string, indent: number): string[] {
+  return [`${spaces(indent)}/** ${value} */`];
+}
+
+function spaces(count: number): string {
+  return " ".repeat(count);
+}
+
+function isSchemaObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/environment.ts

@@ -0,0 +1,101 @@
+import { readFile } from "node:fs/promises";
+import { CodemodeClient, type CodemodeCallOptions, type CodemodeToolFunction } from "./index";
+
+export const CODEMODE_ENVIRONMENT = {
+  url: "OPENGENI_CODEMODE_URL",
+  tokenFile: "OPENGENI_CODEMODE_TOKEN_FILE",
+} as const;
+
+export type CodemodeClientProvider = () => CodemodeClient | Promise<CodemodeClient>;
+
+/** A lazy catalog path. Every nested property remains callable at runtime. */
+export type CodemodeDynamicTool = CodemodeToolFunction & {
+  readonly [segment: string]: CodemodeDynamicTool;
+};
+
+export type CodemodeDynamicTools = {
+  readonly [segment: string]: CodemodeDynamicTool;
+};
+
+/** Catalog-specific generated declarations augment this interface. */
+export interface CodemodeGeneratedTools {}
+
+export type CodemodeToolsNamespace = CodemodeDynamicTools & CodemodeGeneratedTools;
+
+let cachedEnvironmentClient: { key: string; client: CodemodeClient } | null = null;
+
+/**
+ * Build (or reuse) the persistent client for the exact sandbox attempt.
+ * The bearer file is reread for every HTTP request so worker renewal is live.
+ */
+export function environmentCodemodeClient(
+  environment: NodeJS.ProcessEnv = process.env,
+): CodemodeClient {
+  const baseUrl = requiredEnvironment(environment, CODEMODE_ENVIRONMENT.url);
+  const tokenFile = requiredEnvironment(environment, CODEMODE_ENVIRONMENT.tokenFile);
+  const key = `${baseUrl}\u0000${tokenFile}`;
+  if (environment === process.env && cachedEnvironmentClient?.key === key) {
+    return cachedEnvironmentClient.client;
+  }
+  const client = new CodemodeClient({
+    baseUrl,
+    token: async () => await readBearerFile(tokenFile),
+  });
+  if (environment === process.env) cachedEnvironmentClient = { key, client };
+  return client;
+}
+
+/**
+ * Lazy namespace used by ordinary sandbox programs:
+ * `await tools.slack.search({ query: "..." })`.
+ */
+export function createCodemodeTools(
+  client: CodemodeClientProvider = () => environmentCodemodeClient(),
+): CodemodeToolsNamespace {
+  const node = (path: readonly string[]): CodemodeDynamicTool =>
+    new Proxy(
+      (async (args: Record<string, unknown> = {}, options: CodemodeCallOptions = {}) =>
+        await (await client()).callPathValue(path, args, options)) as CodemodeDynamicTool,
+      {
+        get(_target, property) {
+          if (property === "then") return undefined;
+          if (property === Symbol.toStringTag) return "CodemodeTool";
+          if (typeof property !== "string") return undefined;
+          return node([...path, property]);
+        },
+        set() {
+          return false;
+        },
+      },
+    );
+  return new Proxy(Object.create(null) as CodemodeToolsNamespace, {
+    get(_target, property) {
+      if (property === "then") return undefined;
+      if (property === Symbol.toStringTag) return "CodemodeTools";
+      if (typeof property !== "string") return undefined;
+      return node([property]);
+    },
+    set() {
+      return false;
+    },
+  });
+}
+
+export const tools = createCodemodeTools();
+
+async function readBearerFile(path: string): Promise<string> {
+  let token: string;
+  try {
+    token = (await readFile(path, "utf8")).trim();
+  } catch {
+    throw new Error(`${CODEMODE_ENVIRONMENT.tokenFile} is not readable`);
+  }
+  if (!token) throw new Error(`${CODEMODE_ENVIRONMENT.tokenFile} is empty`);
+  return token;
+}
+
+function requiredEnvironment(environment: NodeJS.ProcessEnv, name: string): string {
+  const value = environment[name]?.trim();
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}