@claxedo/agent-runtime-contract 0.8.0

package/dist/index.mjs

@@ -0,0 +1,815 @@
+// ../claxedo-helpers/src/guards.ts
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asRecord(value) {
+  return isRecord(value) ? value : undefined;
+}
+
+// src/values.ts
+function asText(value) {
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+// src/claims.ts
+function jwtClaims(token) {
+  const payload = token?.split(".")[1];
+  if (!payload)
+    return;
+  const base64 = payload.replaceAll("-", "+").replaceAll("_", "/");
+  try {
+    const binary = atob(base64 + "=".repeat((4 - base64.length % 4) % 4));
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    return asRecord(JSON.parse(new TextDecoder().decode(bytes)));
+  } catch {
+    return;
+  }
+}
+function tokensOf(input) {
+  const tokens = asRecord(input?.tokens);
+  return [
+    asText(input?.id_token) ?? asText(tokens?.id_token),
+    asText(input?.access_token) ?? asText(input?.access) ?? asText(tokens?.access_token)
+  ];
+}
+function emailFromClaims(input) {
+  return tokensOf(input).map(emailFromJwt).find((value) => value !== undefined);
+}
+function emailFromJwt(token) {
+  const claims = jwtClaims(token);
+  const openai = asRecord(claims?.["https://api.openai.com/auth"]);
+  return [claims?.email, claims?.preferred_username, openai?.email].map(asText).find((value) => value !== undefined && value.includes("@"));
+}
+function accountIdFromClaims(input) {
+  return tokensOf(input).map(accountIdFromJwt).find((value) => value !== undefined);
+}
+function accountIdFromJwt(token) {
+  const claims = jwtClaims(token);
+  if (!claims)
+    return;
+  const openai = asRecord(claims["https://api.openai.com/auth"]);
+  const named = asText(claims.chatgpt_account_id) ?? asText(openai?.chatgpt_account_id);
+  if (named)
+    return named;
+  const organizations = claims.organizations;
+  return Array.isArray(organizations) ? asText(asRecord(organizations[0])?.id) : undefined;
+}
+// src/connections.ts
+function decodeHarnessConnectionsCatalog(value) {
+  const root = record(value);
+  if (root.status === "unsupported") {
+    if (typeof root.reason !== "string" || !root.reason.trim() || "connections" in root)
+      invalid("unsupported discovery");
+    return { status: "unsupported", reason: root.reason };
+  }
+  if (root.status !== "supported" || !Array.isArray(root.connections))
+    invalid("discovery envelope");
+  return { status: "supported", connections: root.connections.map(decodeConnection) };
+}
+function decodeConnection(value) {
+  const row = record(value);
+  if (typeof row.connectionId !== "string" || !row.connectionId.trim() || typeof row.label !== "string" || !row.label.trim() || typeof row.enabled !== "boolean" || row.readiness !== "ready" && row.readiness !== "unavailable" && row.readiness !== "disabled")
+    invalid("connection reference");
+  return {
+    connectionId: row.connectionId,
+    label: row.label,
+    enabled: row.enabled,
+    readiness: row.readiness,
+    capabilities: decodeCapabilities(row.capabilities),
+    ...row.modelSelection !== undefined ? { modelSelection: decodeModelSelection(row.modelSelection) } : {}
+  };
+}
+function decodeCapabilities(value) {
+  const source = record(value);
+  return {
+    abort: capabilityFlag(source, "abort"),
+    reconnect: capabilityFlag(source, "reconnect"),
+    replay: capabilityFlag(source, "replay"),
+    permissions: capabilityFlag(source, "permissions"),
+    questions: capabilityFlag(source, "questions"),
+    todos: capabilityFlag(source, "todos"),
+    commands: capabilityFlag(source, "commands"),
+    fork: capabilityFlag(source, "fork"),
+    revert: capabilityFlag(source, "revert"),
+    unrevert: capabilityFlag(source, "unrevert"),
+    configOptions: capabilityFlag(source, "configOptions"),
+    subagents: capabilityFlag(source, "subagents")
+  };
+}
+function capabilityFlag(source, key) {
+  const flag = source[key];
+  if (typeof flag !== "boolean")
+    invalid(`capability ${key}`);
+  return flag;
+}
+function decodeModelSelection(value) {
+  const row = record(value);
+  if (row.status === "unsupported" && row.models === undefined)
+    return { status: "unsupported" };
+  if (row.status !== "required" && row.status !== "optional")
+    invalid("model selection");
+  const models = row.models === undefined ? undefined : decodeModels(row.models);
+  if (row.status === "required") {
+    if (!models?.length)
+      invalid("required models");
+    return { status: "required", models };
+  }
+  return { status: "optional", ...models ? { models } : {} };
+}
+function decodeModels(value) {
+  if (!Array.isArray(value))
+    invalid("models");
+  return value.map((item) => {
+    const row = record(item);
+    if (typeof row.providerId !== "string" || !row.providerId || typeof row.modelId !== "string" || !row.modelId || typeof row.name !== "string" || !row.name || row.description !== undefined && typeof row.description !== "string")
+      invalid("model");
+    return {
+      providerId: row.providerId,
+      modelId: row.modelId,
+      name: row.name,
+      ...typeof row.description === "string" ? { description: row.description } : {}
+    };
+  });
+}
+function record(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    invalid("object");
+  return Object.fromEntries(Object.entries(value));
+}
+function invalid(field) {
+  throw new Error(`Invalid agent connection ${field}`);
+}
+// src/tool-names.ts
+var TOOL_NAME_ALIASES = {
+  agent: "task",
+  subagent: "task",
+  spawn_agent: "task",
+  spawnagent: "task",
+  create_subagent: "task",
+  mcp__claxedo__create_subagent: "task",
+  claxedo_create_subagent: "task",
+  command: "bash",
+  shell: "bash",
+  local_shell: "bash",
+  read_file: "read",
+  write_file: "write",
+  edit_file: "edit",
+  ls: "list",
+  askuserquestion: "question",
+  web_search: "websearch"
+};
+function canonicalToolName(name) {
+  const lowered = name.toLowerCase();
+  return TOOL_NAME_ALIASES[lowered] ?? lowered;
+}
+function toolNameAliases() {
+  return Object.entries(TOOL_NAME_ALIASES);
+}
+
+// src/content.ts
+function isSubagentSpawnToolName(toolName) {
+  return canonicalToolName(toolName) === "task";
+}
+function isStringField(container, key) {
+  return typeof container[key] === "string";
+}
+function optionalIs(container, key, check) {
+  return container[key] === undefined || check(container[key]);
+}
+function isTokenUsage(value) {
+  if (!isRecord(value))
+    return false;
+  const cache = value.cache;
+  if (!isRecord(cache) || typeof cache.read !== "number" || typeof cache.write !== "number")
+    return false;
+  if (typeof value.input !== "number" || typeof value.output !== "number" || typeof value.reasoning !== "number")
+    return false;
+  return optionalIs(value, "total", (total) => typeof total === "number");
+}
+function isSpan(value) {
+  return isRecord(value) && typeof value.start === "number" && optionalIs(value, "end", (end) => typeof end === "number");
+}
+function isMessageError(value) {
+  return isRecord(value) && typeof value.name === "string" && isRecord(value.data);
+}
+function isToolState(value) {
+  if (!isRecord(value) || !isRecord(value.input))
+    return false;
+  switch (value.status) {
+    case "pending":
+      return isStringField(value, "raw");
+    case "running":
+      return isSpan(value.time);
+    case "completed":
+      return isStringField(value, "output") && isStringField(value, "title") && isRecord(value.metadata) && isSpan(value.time);
+    case "error":
+      return isStringField(value, "error") && isSpan(value.time);
+    default:
+      return false;
+  }
+}
+function isHandoffEnd(value) {
+  return isRecord(value) && typeof value.id === "string" && typeof value.access === "string";
+}
+function hasPartIdentity(value) {
+  return isRecord(value) && isStringField(value, "id") && isStringField(value, "sessionID") && isStringField(value, "messageID") && isStringField(value, "type");
+}
+function hasVariantFields(part) {
+  switch (part.type) {
+    case "text":
+      return isStringField(part, "text");
+    case "reasoning":
+      return isStringField(part, "text") && isSpan(part.time);
+    case "file":
+      return isStringField(part, "mime") && isStringField(part, "url");
+    case "tool":
+      return isStringField(part, "callID") && isStringField(part, "tool") && isToolState(part.state);
+    case "subtask":
+      return isStringField(part, "prompt") && isStringField(part, "description") && isStringField(part, "agent");
+    case "step-start":
+      return optionalIs(part, "snapshot", (snapshot) => typeof snapshot === "string");
+    case "step-finish":
+      return isStringField(part, "reason") && typeof part.cost === "number" && isTokenUsage(part.tokens);
+    case "snapshot":
+      return isStringField(part, "snapshot");
+    case "patch":
+      return isStringField(part, "hash") && Array.isArray(part.files) && part.files.every((file) => typeof file === "string");
+    case "agent":
+      return isStringField(part, "name");
+    case "retry":
+      return typeof part.attempt === "number" && isMessageError(part.error) && isRecord(part.time) && typeof part.time.created === "number";
+    case "compaction":
+      return typeof part.auto === "boolean";
+    case "handoff":
+      return isHandoffEnd(part.from) && isHandoffEnd(part.to);
+    default:
+      return false;
+  }
+}
+function isAgentContentPart(value) {
+  return hasPartIdentity(value) && hasVariantFields(value);
+}
+function parseAgentContentPart(value) {
+  return isAgentContentPart(value) ? value : undefined;
+}
+function isAgentMessageInfo(value) {
+  return isRecord(value) && isStringField(value, "id") && isStringField(value, "role") && isStringField(value, "sessionID") && optionalIs(value, "parentID", (parentID) => typeof parentID === "string") && optionalIs(value, "tokens", isTokenUsage) && optionalIs(value, "error", isMessageError);
+}
+function isAgentMessage(value) {
+  return isRecord(value) && isAgentMessageInfo(value.info) && Array.isArray(value.parts) && value.parts.every(isAgentContentPart);
+}
+function parseAgentMessage(value) {
+  return isAgentMessage(value) ? value : undefined;
+}
+// src/credential-broker-errors.ts
+var CREDENTIAL_BROKER_ERRORS = {
+  binding_route_required: {
+    fault: "harness",
+    message: "The credential broker serves binding paths only"
+  },
+  runtime_token_required: {
+    fault: "harness",
+    message: "The request carried no runtime token, or two that disagree"
+  },
+  runtime_token_invalid: {
+    fault: "credential",
+    message: "The runtime token could not be verified"
+  },
+  binding_not_permitted: {
+    fault: "harness",
+    message: "This runtime token does not name that binding"
+  },
+  binding_unavailable: {
+    fault: "credential",
+    message: "The binding names no account this runtime can spend"
+  },
+  credential_unavailable: {
+    fault: "credential",
+    message: "The account behind this binding has no readable value"
+  },
+  binding_destination_invalid: {
+    fault: "harness",
+    message: "The binding's destination is not a usable vendor origin"
+  },
+  binding_injection_invalid: {
+    fault: "harness",
+    message: "The binding names a header the broker cannot set"
+  },
+  request_outside_policy: {
+    fault: "harness",
+    message: "The request is outside the routes this binding allows"
+  },
+  upstream_unavailable: {
+    fault: "model",
+    message: "The vendor could not be reached"
+  },
+  upstream_redirect_refused: {
+    fault: "model",
+    message: "The vendor answered with a redirect, which the broker does not follow"
+  },
+  broker_authority_unavailable: {
+    fault: "harness",
+    message: "The credential authority could not be reached"
+  },
+  loopback_required: {
+    fault: "harness",
+    message: "The credential broker answers loopback callers only"
+  }
+};
+function credentialBrokerErrorCode(message) {
+  const inBody = codeFromBody(message);
+  if (inBody)
+    return inBody;
+  const inProse = codeInProse.exec(message)?.[1];
+  return inProse && isCredentialBrokerErrorCode(inProse) ? inProse : undefined;
+}
+var codeInProse = new RegExp(`\\b(${Object.keys(CREDENTIAL_BROKER_ERRORS).join("|")})\\b`);
+function codeFromBody(message) {
+  const start = message.indexOf("{");
+  const end = message.lastIndexOf("}");
+  if (start === -1 || end <= start)
+    return;
+  try {
+    const body = JSON.parse(message.slice(start, end + 1));
+    const error = isRecord(body) ? body.error : undefined;
+    const code = typeof error === "string" ? error : isRecord(error) ? error.code : undefined;
+    return typeof code === "string" && isCredentialBrokerErrorCode(code) ? code : undefined;
+  } catch {
+    return;
+  }
+}
+function isCredentialBrokerErrorCode(value) {
+  return Object.hasOwn(CREDENTIAL_BROKER_ERRORS, value);
+}
+// src/errors.ts
+var AGENT_RUNTIME_ERROR_CODES = [
+  "selection_required",
+  "harness_unavailable",
+  "workspace_offline",
+  "unsupported_operation",
+  "replay_gap",
+  "upstream_error",
+  "invalid_execution_binding"
+];
+
+class AgentRuntimeContractError extends Error {
+  detail;
+  constructor(detail) {
+    super(detail.message);
+    this.detail = detail;
+    this.name = "AgentRuntimeContractError";
+  }
+}
+var BINDING_FIELDS = ["sessionId", "workspaceId", "directory", "connectionId", "upstreamSessionId"];
+function assertAgentExecutionBinding(binding, expected = binding) {
+  if ((binding.scope ?? "workspace") !== (expected.scope ?? "workspace")) {
+    throw new AgentRuntimeContractError({ code: "invalid_execution_binding", field: "scope", message: "execution binding scope mismatch" });
+  }
+  if (binding.scope !== undefined && binding.scope !== "workspace") {
+    throw new AgentRuntimeContractError({ code: "invalid_execution_binding", field: "scope", message: "workspace execution scope is required" });
+  }
+  for (const field of BINDING_FIELDS) {
+    const value = binding[field];
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new AgentRuntimeContractError({
+        code: "invalid_execution_binding",
+        field,
+        message: `execution binding ${field} is required`
+      });
+    }
+    if (binding[field] !== expected[field]) {
+      throw new AgentRuntimeContractError({
+        code: "invalid_execution_binding",
+        field,
+        message: `execution binding ${field} mismatch`
+      });
+    }
+  }
+  return binding;
+}
+// src/events.ts
+var AGENT_PRESENTATION_EVENT_TYPE_REGISTRY = {
+  "message.updated": true,
+  "message.removed": true,
+  "message.part.updated": true,
+  "message.part.removed": true,
+  "message.part.delta": true,
+  "message.completed": true,
+  "permission.asked": true,
+  "permission.replied": true,
+  "question.asked": true,
+  "question.replied": true,
+  "question.rejected": true,
+  "todo.updated": true,
+  "session.status": true,
+  "session.idle": true,
+  "session.error": true,
+  "session.updated": true,
+  "session.diff": true,
+  "session.compacted": true,
+  "session.agent": true,
+  "session.config": true,
+  "session.usage": true,
+  "runtime.diagnostic": true,
+  "server.connected": true,
+  "server.heartbeat": true
+};
+function isAgentPresentationEventType(value) {
+  return Object.hasOwn(AGENT_PRESENTATION_EVENT_TYPE_REGISTRY, value);
+}
+var AGENT_PRESENTATION_EVENT_TYPES = Object.keys(AGENT_PRESENTATION_EVENT_TYPE_REGISTRY).filter(isAgentPresentationEventType);
+// src/files.ts
+function isAgentReviewFileDiff(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  if (!("file" in value) || typeof value.file !== "string")
+    return false;
+  if (!("additions" in value) || typeof value.additions !== "number")
+    return false;
+  if (!("deletions" in value) || typeof value.deletions !== "number")
+    return false;
+  if ("patch" in value && value.patch !== undefined && typeof value.patch !== "string")
+    return false;
+  if ("before" in value && value.before !== undefined && typeof value.before !== "string")
+    return false;
+  if ("after" in value && value.after !== undefined && typeof value.after !== "string")
+    return false;
+  if (!("status" in value) || value.status === undefined)
+    return true;
+  return value.status === "added" || value.status === "deleted" || value.status === "modified";
+}
+function agentReviewFileDiffList(value) {
+  if (Array.isArray(value) && value.every(isAgentReviewFileDiff))
+    return value;
+  if (Array.isArray(value))
+    return value.filter(isAgentReviewFileDiff);
+  if (isAgentReviewFileDiff(value))
+    return [value];
+  if (!value || typeof value !== "object")
+    return [];
+  return Object.values(value).filter(isAgentReviewFileDiff);
+}
+// src/harness-effort.ts
+var HARNESS_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
+function isHarnessEffortLevel(value) {
+  return HARNESS_EFFORT_LEVELS.includes(value);
+}
+var NO_HARNESS_EFFORT = { status: "unsupported", models: [] };
+function harnessEffortVerdict(catalog, modelID, effort) {
+  if (!effort)
+    return "accepted";
+  if (!catalog)
+    return "unknown";
+  if (catalog.status === "unsupported")
+    return "refused";
+  if (catalog.status === "unresolved")
+    return "unknown";
+  const row = modelID ? catalog.models.find((model) => model.modelID === modelID) : undefined;
+  if (!row)
+    return "refused";
+  return row.levels.includes(effort) ? "accepted" : "refused";
+}
+function parseHarnessEffortLevels(value) {
+  if (!isRecord(value))
+    return;
+  const status = value.status;
+  if (status !== "resolved" && status !== "unresolved" && status !== "unsupported")
+    return;
+  const models = Array.isArray(value.models) ? value.models : [];
+  return {
+    status,
+    models: models.flatMap((entry) => {
+      if (!isRecord(entry))
+        return [];
+      const modelID = entry.modelID;
+      if (typeof modelID !== "string" || !modelID)
+        return [];
+      const levels = Array.isArray(entry.levels) ? entry.levels.filter((level) => typeof level === "string" && !!level) : [];
+      return [{
+        modelID,
+        levels,
+        ...typeof entry.default === "string" && entry.default ? { default: entry.default } : {}
+      }];
+    })
+  };
+}
+function harnessEffortRefusal(input) {
+  if (input.catalog?.status !== "resolved")
+    return;
+  if (!input.effort)
+    return;
+  if (harnessEffortVerdict(input.catalog, input.modelID, input.effort) !== "refused")
+    return;
+  const levels = input.catalog.models.find((model) => model.modelID === input.modelID)?.levels ?? [];
+  return `The ${input.harness} harness does not run ${input.modelID ?? "its default model"} at effort ${input.effort}; ${levels.length > 0 ? `it accepts ${levels.join(", ")}` : "it accepts no effort for that model"}`;
+}
+// src/harness-table.ts
+var HARNESS_IDS = ["claude", "codex", "cursor"];
+var HARNESS_TABLE = {
+  claude: {
+    label: "Claude Code",
+    vendor: "Anthropic",
+    providerIds: ["claude-sdk", "claude-acp", "anthropic"],
+    connectProvider: "claude-sdk",
+    vendorProvider: "anthropic",
+    machineLoginServes: ["claude-sdk", "claude-acp"]
+  },
+  codex: {
+    label: "Codex",
+    vendor: "OpenAI",
+    providerIds: ["codex-app-server", "openai"],
+    connectProvider: "codex-app-server",
+    vendorProvider: "openai",
+    machineLoginServes: ["codex-app-server", "openai"]
+  },
+  cursor: {
+    label: "Cursor",
+    vendor: "Cursor",
+    providerIds: ["cursor-sdk", "cursor-acp", "cursor"],
+    connectProvider: "cursor-sdk",
+    vendorProvider: "cursor",
+    machineLoginServes: ["cursor-acp"]
+  }
+};
+function isHarnessId(value) {
+  return HARNESS_IDS.includes(value);
+}
+function harnessForProviderId(id) {
+  return HARNESS_IDS.find((harness) => HARNESS_TABLE[harness].providerIds.includes(id));
+}
+function harnessBindingIds(harness) {
+  const record2 = HARNESS_TABLE[harness];
+  return record2.providerIds.filter((id) => id !== record2.vendorProvider);
+}
+// src/harnesses.ts
+var AGENT_HARNESS_DEFINITIONS = [
+  {
+    key: "claude",
+    id: "claude",
+    access: "native",
+    label: "Claude",
+    authEnv: "ANTHROPIC_API_KEY",
+    authSlot: "anthropic"
+  },
+  {
+    key: "codex",
+    id: "codex",
+    access: "native",
+    label: "Codex",
+    authEnv: "OPENAI_API_KEY",
+    authSlot: "openai"
+  },
+  {
+    key: "cursor",
+    id: "cursor",
+    access: "native",
+    label: "Cursor",
+    authEnv: "CURSOR_API_KEY",
+    authSlot: "cursor"
+  },
+  {
+    key: "pi",
+    id: "pi",
+    access: "native",
+    label: "Pi",
+    authEnv: null,
+    authSlot: null
+  },
+  {
+    key: "opencode",
+    id: "opencode",
+    access: "native",
+    label: "OpenCode",
+    authEnv: null,
+    authSlot: null
+  }
+];
+var AGENT_HARNESS_IDS = ["claude", "codex", "cursor", "pi", "opencode"];
+var AGENT_HARNESS_ACCESSES = ["connection", "native"];
+var AGENT_HARNESS_KEYS = AGENT_HARNESS_DEFINITIONS.map((item) => item.key);
+var ACP_CONNECTION_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+function isAcpConnectionId(id) {
+  return ACP_CONNECTION_ID_PATTERN.test(id);
+}
+function harnessDefinition(input) {
+  if (typeof input === "string")
+    return AGENT_HARNESS_DEFINITIONS.find((item) => item.key === input);
+  return AGENT_HARNESS_DEFINITIONS.find((item) => item.id === input.id && item.access === input.access);
+}
+function isAgentHarnessId(id) {
+  return AGENT_HARNESS_IDS.includes(id);
+}
+function isAgentHarnessAccess(access) {
+  return AGENT_HARNESS_ACCESSES.includes(access);
+}
+function normalizeAgentHarnessTransport(input) {
+  if (input === undefined)
+    return;
+  if (input === "stdio" || input === "streamable-http" || input === "websocket")
+    return input;
+  return;
+}
+function harnessKey(input) {
+  const definition = harnessDefinition(input);
+  if (definition)
+    return definition.key;
+  if (input.access === "connection" && isAcpConnectionId(input.id))
+    return `connection:${input.id}`;
+  return;
+}
+function normalizeHarnessIdentity(input) {
+  if (typeof input === "string") {
+    if (isAgentHarnessId(input))
+      return { id: input, access: "native" };
+    return;
+  }
+  const row = asRecord(input);
+  if (!row)
+    return;
+  const idInput = typeof row.id === "string" ? row.id : undefined;
+  const accessInput = typeof row.access === "string" ? row.access : undefined;
+  const id = idInput && isAgentHarnessId(idInput) ? idInput : idInput && accessInput === "connection" && isAcpConnectionId(idInput) ? idInput : undefined;
+  const access = accessInput && isAgentHarnessAccess(accessInput) ? accessInput : id ? "native" : undefined;
+  if (!id || !access)
+    return;
+  return { id, access };
+}
+var HARNESS_INSTRUCTION_CHANNELS = [
+  "turn-system-prompt",
+  "thread-start",
+  "prompt-prefix",
+  "none"
+];
+// src/question-answers.ts
+var MULTI_SELECT_JOIN = ", ";
+function reconstructQuestionAnswers(questions, answers) {
+  return questions.map((question) => {
+    const value = answers[question.question];
+    if (typeof value !== "string" || !value)
+      return [];
+    const labels = new Set(question.optionLabels);
+    if (labels.has(value) || !question.multiple)
+      return [value];
+    const selected = value.split(MULTI_SELECT_JOIN);
+    return selected.length > 1 && selected.every((label) => labels.has(label)) ? selected : [value];
+  });
+}
+// src/session-group.ts
+var SESSION_GROUP_SLOTS = ["primary", "planning", "implementation", "review"];
+function isSessionGroupSlot(value) {
+  return SESSION_GROUP_SLOTS.includes(value);
+}
+function parseSessionModelGroup(input) {
+  if (!isRecord(input))
+    return { field: "group", message: "group must be an object of slot entries" };
+  const group = {};
+  for (const [slot, value] of Object.entries(input)) {
+    if (!isSessionGroupSlot(slot)) {
+      return { field: `group.${slot}`, message: `group slot must be one of ${SESSION_GROUP_SLOTS.join(", ")}` };
+    }
+    const entry = parseEntry(`group.${slot}`, value);
+    if ("field" in entry)
+      return entry;
+    group[slot] = entry.entry;
+  }
+  return { group };
+}
+function sessionVariantForEffort(effort) {
+  return effort ? { variant: effort } : {};
+}
+function sessionModelGroupJson(group) {
+  return group && Object.keys(group).length > 0 ? JSON.stringify(group) : null;
+}
+function parseStoredSessionModelGroup(json) {
+  if (!json)
+    return;
+  const parsed = jsonOrUndefined(json);
+  if (parsed === undefined)
+    return;
+  const result = parseSessionModelGroup(parsed);
+  return "group" in result && Object.keys(result.group).length > 0 ? result.group : undefined;
+}
+function jsonOrUndefined(json) {
+  try {
+    return JSON.parse(json);
+  } catch {
+    return;
+  }
+}
+function parseEntry(field, value) {
+  if (!isRecord(value))
+    return { field, message: "group slot must be an object" };
+  const harness = normalizeHarnessIdentity(value.harness);
+  if (!harness)
+    return { field: `${field}.harness`, message: "group slot needs a known harness" };
+  const model = parseModel(value.model);
+  if (!model)
+    return { field: `${field}.model`, message: "group slot needs a model with providerID and modelID" };
+  if (value.effort !== undefined && (typeof value.effort !== "string" || !value.effort)) {
+    return { field: `${field}.effort`, message: "group slot effort must be a non-empty string" };
+  }
+  return {
+    entry: {
+      harness,
+      model,
+      ...typeof value.effort === "string" ? { effort: value.effort } : {}
+    }
+  };
+}
+function parseModel(value) {
+  if (!isRecord(value))
+    return;
+  const providerID = value.providerID;
+  const modelID = value.modelID;
+  if (typeof providerID !== "string" || !providerID)
+    return;
+  if (typeof modelID !== "string" || !modelID)
+    return;
+  return { providerID, modelID };
+}
+// src/sessions.ts
+function connectionIdForHarness(harness) {
+  return `${harness.access}:${harness.id}`;
+}
+// src/usage-windows.ts
+var USAGE_WINDOW_NAMES = {
+  claude: { five_hour: "session", seven_day: "weekly", seven_day_opus: "weekly_opus" },
+  codex: {
+    primary_window: "session",
+    secondary_window: "weekly",
+    credit_window: "credits",
+    spark_primary_window: "spark_session",
+    spark_secondary_window: "spark_weekly"
+  },
+  cursor: { primary_window: "plan", secondary_window: "auto", tertiary_window: "api" }
+};
+var CODEX_WINDOW_NAME_BY_SECONDS = {
+  18000: "session",
+  604800: "weekly"
+};
+
+// src/index.ts
+var AGENT_RUNTIME_CONTRACT_VERSION = 1;
+export {
+  toolNameAliases,
+  sessionVariantForEffort,
+  sessionModelGroupJson,
+  reconstructQuestionAnswers,
+  parseStoredSessionModelGroup,
+  parseSessionModelGroup,
+  parseHarnessEffortLevels,
+  parseAgentMessage,
+  parseAgentContentPart,
+  normalizeHarnessIdentity,
+  normalizeAgentHarnessTransport,
+  isSubagentSpawnToolName,
+  isSessionGroupSlot,
+  isRecord,
+  isHarnessId,
+  isHarnessEffortLevel,
+  isCredentialBrokerErrorCode,
+  isAgentReviewFileDiff,
+  isAgentPresentationEventType,
+  isAgentMessageInfo,
+  isAgentMessage,
+  isAgentHarnessId,
+  isAgentHarnessAccess,
+  isAgentContentPart,
+  isAcpConnectionId,
+  harnessKey,
+  harnessForProviderId,
+  harnessEffortVerdict,
+  harnessEffortRefusal,
+  harnessDefinition,
+  harnessBindingIds,
+  emailFromClaims,
+  decodeModelSelection,
+  decodeHarnessConnectionsCatalog,
+  credentialBrokerErrorCode,
+  connectionIdForHarness,
+  canonicalToolName,
+  assertAgentExecutionBinding,
+  asText,
+  asRecord,
+  agentReviewFileDiffList,
+  accountIdFromClaims,
+  USAGE_WINDOW_NAMES,
+  SESSION_GROUP_SLOTS,
+  NO_HARNESS_EFFORT,
+  HARNESS_TABLE,
+  HARNESS_INSTRUCTION_CHANNELS,
+  HARNESS_IDS,
+  HARNESS_EFFORT_LEVELS,
+  CREDENTIAL_BROKER_ERRORS,
+  CODEX_WINDOW_NAME_BY_SECONDS,
+  AgentRuntimeContractError,
+  AGENT_RUNTIME_ERROR_CODES,
+  AGENT_RUNTIME_CONTRACT_VERSION,
+  AGENT_PRESENTATION_EVENT_TYPE_REGISTRY,
+  AGENT_PRESENTATION_EVENT_TYPES,
+  AGENT_HARNESS_KEYS,
+  AGENT_HARNESS_IDS,
+  AGENT_HARNESS_DEFINITIONS,
+  AGENT_HARNESS_ACCESSES,
+  ACP_CONNECTION_ID_PATTERN
+};