@howarewoo/pi-subagents 0.0.0-stage → 0.2.0

package/src/model-policy.ts

@@ -0,0 +1,100 @@
+import type { ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { getSupportedThinkingLevels } from "@earendil-works/pi-ai/compat";
+
+export const EFFORTS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ModelSelection = Readonly<{
+  provider: string;
+  id: string;
+  effort: (typeof EFFORTS)[number];
+}>;
+export type ModelPolicy = Readonly<{
+  models?: readonly ModelSelection[];
+  model?: ModelSelection;
+  prewalk?: ModelSelection;
+}>;
+export function modelSelection(value: unknown): ModelSelection {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Unsupported model selection: expected exact provider, id and effort");
+  const item = value as Record<string, unknown>;
+  if (
+    Object.keys(item).some((key) => !["provider", "id", "effort"].includes(key)) ||
+    typeof item.provider !== "string" ||
+    !item.provider.trim() ||
+    typeof item.id !== "string" ||
+    !item.id.trim() ||
+    !EFFORTS.includes(item.effort as ModelSelection["effort"])
+  )
+    throw new Error("Unsupported model selection: expected exact provider, id and effort");
+  return { provider: item.provider, id: item.id, effort: item.effort as ModelSelection["effort"] };
+}
+export function sameSelection(a: ModelSelection, b: ModelSelection): boolean {
+  return a.provider === b.provider && a.id === b.id && a.effort === b.effort;
+}
+export function allowsModel(policy: ModelPolicy, selection: ModelSelection): boolean {
+  return (
+    policy.models === undefined || policy.models.some((item) => sameSelection(item, selection))
+  );
+}
+export function narrowModelPolicy(
+  base: ModelPolicy,
+  value: Record<string, unknown>,
+  operator: boolean,
+): ModelPolicy {
+  let models = base.models;
+  if (value.models !== undefined) {
+    if (!Array.isArray(value.models) || value.models.length > 64)
+      throw new Error("models must be a bounded exact selection array");
+    models = value.models.map(modelSelection);
+    if (
+      !operator &&
+      models.some((item) => !base.models?.some((allowed) => sameSelection(item, allowed)))
+    )
+      throw new Error("Cannot mint model grants");
+  }
+  const policy: ModelPolicy = {
+    models,
+    model: value.model === undefined ? base.model : modelSelection(value.model),
+    prewalk: value.prewalk === undefined ? base.prewalk : modelSelection(value.prewalk),
+  };
+  for (const selection of [policy.model, policy.prewalk])
+    if (selection && !models?.some((item) => sameSelection(item, selection)))
+      throw new Error("Model and prewalk selections require an exact operator model grant");
+  if (
+    !operator &&
+    policy.prewalk &&
+    (!base.prewalk || !sameSelection(policy.prewalk, base.prewalk))
+  )
+    throw new Error("Cannot mint prewalk grants");
+  return policy;
+}
+export function validateModelSelection(
+  ctx: Pick<ExtensionToolContext, "modelRegistry" | "scopedModels">,
+  selection: ModelSelection,
+) {
+  const registry = ctx.modelRegistry;
+  const model = registry.find(selection.provider, selection.id);
+  if (!model || model.api === "pi-virtual" || !registry.getProvider(model.provider))
+    throw new Error("Unsupported or unknown physical model selection");
+  if (
+    !registry
+      .getAvailable()
+      .some((item) => item.provider === model.provider && item.id === model.id) ||
+    !registry.hasConfiguredAuth(model)
+  )
+    throw new Error("Model selection unavailable or missing configured parent authentication");
+  if (
+    ctx.scopedModels.length &&
+    !ctx.scopedModels.some(
+      (item) =>
+        item.model.provider === model.provider &&
+        item.model.id === model.id &&
+        (item.thinkingLevel === undefined || item.thinkingLevel === selection.effort),
+    )
+  )
+    throw new Error("Model selection outside parent scoped models/effort");
+  if (![model.contextWindow, model.maxTokens].every((limit) => Number.isFinite(limit) && limit > 0))
+    throw new Error("Model selection requires known finite context and output limits");
+  if (!getSupportedThinkingLevels(model).includes(selection.effort))
+    throw new Error("Unsupported model effort; silent coercion is denied");
+  return model;
+}

package/src/outcomes.ts

@@ -0,0 +1,110 @@
+import { compile, type Validator } from "@earendil-works/pi-schema";
+import { Type } from "typebox";
+import { link, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+/** Deliberately finite JSON Schema subset: no references, regexes or executable extensions. */
+export function resultValidator(schema: unknown): Validator {
+  if (JSON.stringify(schema)?.length > 16384)
+    throw new Error("Result schema exceeds 16384 characters");
+  let nodes = 0;
+  function visit(value: unknown, depth: number): void {
+    if (++nodes > 256 || depth > 16) throw new Error("Result schema complexity limit");
+    if (typeof value === "boolean") return;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error("Result schema must be an object or boolean");
+    const node = value as Record<string, unknown>;
+    for (const [key, item] of Object.entries(node)) {
+      if (key === "properties") {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+          throw new Error("Schema properties must be an object");
+        for (const child of Object.values(item)) visit(child, depth + 1);
+      } else if (key === "items" || key === "additionalProperties") visit(item, depth + 1);
+      else if (key === "type") {
+        if (
+          !["object", "array", "string", "number", "integer", "boolean", "null"].includes(
+            item as string,
+          )
+        )
+          throw new Error("Unsupported result schema type");
+      } else if (["title", "description"].includes(key)) {
+        if (typeof item !== "string") throw new Error(`Schema ${key} must be text`);
+      } else if (key === "required") {
+        if (
+          !Array.isArray(item) ||
+          !item.every((v) => typeof v === "string") ||
+          new Set(item).size !== item.length
+        )
+          throw new Error("Schema required must contain distinct strings");
+      } else if (key === "enum") {
+        if (!Array.isArray(item) || !item.length) throw new Error("Schema enum must be nonempty");
+      } else if (key === "const") {
+        /* JSON literal; never interpreted as a schema */
+      } else if (
+        [
+          "minimum",
+          "maximum",
+          "exclusiveMinimum",
+          "exclusiveMaximum",
+          "multipleOf",
+          "minLength",
+          "maxLength",
+          "minItems",
+          "maxItems",
+          "minProperties",
+          "maxProperties",
+        ].includes(key)
+      ) {
+        if (
+          typeof item !== "number" ||
+          !Number.isFinite(item) ||
+          (key === "multipleOf" && item <= 0) ||
+          (((key.startsWith("min") && key !== "minimum") ||
+            (key.startsWith("max") && key !== "maximum")) &&
+            (!Number.isSafeInteger(item) || item < 0))
+        )
+          throw new Error(`Invalid schema bound: ${key}`);
+      } else throw new Error(`Unsupported result schema keyword: ${key}`);
+    }
+  }
+  visit(schema, 0);
+  return compile(schema as object | boolean);
+}
+
+export const submissionParameters = Type.Object(
+  { value: Type.Unknown() },
+  { additionalProperties: false },
+);
+export type StructuredOutcome = {
+  validation: "awaiting" | "invalid" | "submitted";
+  attempts: number;
+  errors: string[];
+  value?: unknown;
+  finalized: boolean;
+};
+
+/** Atomic, exclusive publication; callers supply only fixed names inside a newly owned task directory. */
+export async function saveOutcomeArtifact(
+  directory: string,
+  name: "result.txt" | "structured.json",
+  content: string,
+): Promise<string> {
+  if (name !== "result.txt" && name !== "structured.json")
+    throw new Error("Unsupported outcome artifact filename");
+  const target = join(directory, name);
+  const temporary = join(directory, `.outcome-${randomUUID()}`);
+  await writeFile(temporary, content, { flag: "wx", mode: 0o600 });
+  try {
+    await link(temporary, target);
+  } finally {
+    await unlink(temporary);
+  }
+  return target;
+}
+
+export function clippedText(text: string, maximum = 2048): string {
+  return text.length > maximum
+    ? text.slice(0, maximum) + "\n[Preview truncated; full output in artifact/transcript]"
+    : text;
+}