@hobin/developer 0.1.4 → 0.1.6

package/extensions/state.ts

@@ -1,5 +1,16 @@
-export const PROTOCOL = "developer/v3" as const;
-export const PREVIOUS_PROTOCOL = "developer/v2" as const;
+import { applyDeveloperEvent, developerSnapshot, initialState } from "./machine.ts";
+
+export {
+  applyDeveloperEvent,
+  canApplyDeveloperEvent,
+  developerMachine,
+  developerSnapshot,
+  initialState,
+} from "./machine.ts";
+
+export const PROTOCOL = "developer/v4" as const;
+export const PREVIOUS_PROTOCOL = "developer/v3" as const;
+export const OLDER_PROTOCOL = "developer/v2" as const;
 export const LEGACY_PROTOCOL = "developer/v1" as const;
 export const MODE_ENTRY = "developer.mode" as const;
 export const FOCUS_ENTRY = "developer.question-focus" as const;
@@ -7,10 +18,17 @@ export const ROUTE_TOOL = "developer_route_question" as const;
 export const JUDGMENT_TOOL = "developer_record_judgment" as const;
 export const LEGACY_ROUTE_TOOL = "route_question" as const;
 export const LEGACY_JUDGMENT_TOOL = "record_judgment" as const;
+export const MAX_RESPONSE_FIELDS = 20;
+export const MAX_RESPONSE_OPTIONS = 20;
+export const MAX_RESPONSE_IDENTIFIER_CHARS = 64;
+export const MAX_RESPONSE_TEXT_CHARS = 2_000;
 
 export type DeveloperMode = "off" | "on" | "strict";
 export type JudgmentStatus = "resolved" | "needs-evidence" | "not-applicable" | "blocked";
-export type PendingQuestionStatus = "needs-evidence" | "blocked";
+export type PendingQuestionStatus = "open" | "blocked";
+export type QuestionResolutionOwner = "agent" | "user" | "environment" | "unknown";
+export type QuestionGate = "none" | "before-direct" | "before-completion";
+export type QuestionUpdateStatus = "resolved" | "not-applicable" | "open" | "blocked";
 export type DirectExecutionProfile = "ordinary" | "behavior-preserving-structure";
 
 export interface ModeEvent {
@@ -31,6 +49,11 @@ export interface DirectStepContract {
   verification: string;
 }
 
+export interface RouteAlternative {
+  owner: string;
+  reason: string;
+}
+
 export interface RouteEvent {
   protocol: typeof PROTOCOL;
   kind: "route";
@@ -39,19 +62,51 @@ export interface RouteEvent {
   owner: string;
   reason: string;
   knownEvidence: string[];
+  consideredAlternatives: RouteAlternative[];
   targetQuestionId?: string;
   methodLocation?: string;
   executionProfile?: DirectExecutionProfile;
   directStep?: DirectStepContract;
 }
 
+export interface ChoiceResponseOption {
+  value: string;
+  label: string;
+  description?: string;
+  detailPrompt?: string;
+}
+
+export interface ChoiceResponseField {
+  id: string;
+  prompt: string;
+  description?: string;
+  options: ChoiceResponseOption[];
+}
+
+export interface ChoiceResponseSpec {
+  kind: "choice-form";
+  fields: ChoiceResponseField[];
+}
+
 export interface PendingQuestion {
   id: string;
   question: string;
+  context?: string;
+  responseSpec?: ChoiceResponseSpec;
   status: PendingQuestionStatus;
+  resolutionOwner: QuestionResolutionOwner;
+  gate: QuestionGate;
+  resolutionCriteria: string;
   sourceRouteId: string;
 }
 
+export interface QuestionUpdate {
+  questionId: string;
+  status: QuestionUpdateStatus;
+  result: string;
+  basis: string[];
+}
+
 export interface JudgmentEvent {
   protocol: typeof PROTOCOL;
   kind: "judgment";
@@ -62,6 +117,7 @@ export interface JudgmentEvent {
   result: string;
   basis: string[];
   openedQuestions: PendingQuestion[];
+  questionUpdates: QuestionUpdate[];
   artifacts: string[];
   changedArtifacts: boolean;
 }
@@ -73,108 +129,40 @@ export interface DeveloperState {
   activeRoute?: RouteEvent;
   lastRoute?: RouteEvent;
   lastJudgment?: JudgmentEvent;
+  routeHistory: RouteEvent[];
+  judgmentHistory: JudgmentEvent[];
   pendingQuestions: PendingQuestion[];
   focusedQuestionId?: string;
+  rerouteRequired: boolean;
   implementationFramingRequired: boolean;
   verificationRequired: boolean;
 }
 
-export const initialState = (): DeveloperState => ({
-  mode: "off",
-  pendingQuestions: [],
-  implementationFramingRequired: false,
-  verificationRequired: false,
-});
-
-export type ProtocolState = "idle" | "needs-judgment" | "needs-evidence" | "needs-verification" | "blocked";
+export type ProtocolState =
+  | "idle"
+  | "needs-judgment"
+  | "needs-evidence"
+  | "needs-answer"
+  | "needs-routing"
+  | "needs-verification"
+  | "blocked";
 
 export function protocolState(state: DeveloperState): ProtocolState {
-  if (state.activeRoute) return "needs-judgment";
-  if (state.pendingQuestions.some((question) => question.status === "blocked")) return "blocked";
-  if (state.pendingQuestions.length > 0) return "needs-evidence";
-  if (state.verificationRequired) return "needs-verification";
+  const snapshot = developerSnapshot(state);
+  if (!snapshot.matches({ route: "idle" })) return "needs-judgment";
+  if (
+    snapshot.hasTag("blocks-direct") ||
+    state.pendingQuestions.some((question) => question.status === "blocked")
+  )
+    return "blocked";
+  if (state.pendingQuestions.some((question) => question.resolutionOwner === "user"))
+    return "needs-answer";
+  if (snapshot.matches({ questions: "open" })) return "needs-evidence";
+  if (snapshot.hasTag("reroute-required")) return "needs-routing";
+  if (snapshot.hasTag("verification-required")) return "needs-verification";
   return "idle";
 }
 
-function upsertQuestion(questions: PendingQuestion[], next: PendingQuestion): PendingQuestion[] {
-  return [...questions.filter((question) => question.id !== next.id), next];
-}
-
-export function applyDeveloperEvent(state: DeveloperState, event: DeveloperEvent): DeveloperState {
-  if (event.kind === "mode") {
-    if (event.mode === "off") return initialState();
-    return { ...state, mode: event.mode };
-  }
-
-  if (event.kind === "focus") {
-    if (!state.pendingQuestions.some((question) => question.id === event.questionId)) return state;
-    return { ...state, focusedQuestionId: event.questionId };
-  }
-
-  if (event.kind === "route") {
-    if (state.activeRoute) return state;
-    return {
-      ...state,
-      activeRoute: event,
-      lastRoute: event,
-      focusedQuestionId:
-        event.targetQuestionId === state.focusedQuestionId ? undefined : state.focusedQuestionId,
-    };
-  }
-
-  if (!state.activeRoute || state.activeRoute.routeId !== event.routeId) return state;
-
-  const route = state.activeRoute;
-  const judgment = { ...event, question: route.question, owner: route.owner };
-  let pending = [...state.pendingQuestions];
-  const remainsOpen = event.status === "needs-evidence" || event.status === "blocked";
-
-  if (route.targetQuestionId) {
-    pending = pending.filter((question) => question.id !== route.targetQuestionId);
-    if (remainsOpen) {
-      pending = upsertQuestion(pending, {
-        id: route.targetQuestionId,
-        question: route.question,
-        status: event.status === "blocked" ? "blocked" : "needs-evidence",
-        sourceRouteId: route.routeId,
-      });
-    }
-  } else if (remainsOpen) {
-    pending = upsertQuestion(pending, {
-      id: `question:${route.routeId}`,
-      question: route.question,
-      status: event.status === "blocked" ? "blocked" : "needs-evidence",
-      sourceRouteId: route.routeId,
-    });
-  }
-
-  for (const question of event.openedQuestions) pending = upsertQuestion(pending, question);
-
-  const closesFramingGate =
-    (route.owner === "sketch" || route.owner === "signal") &&
-    (event.status === "resolved" || event.status === "not-applicable");
-  const opensFramingGate = route.owner === "model" && event.status === "resolved";
-  let implementationFramingRequired = state.implementationFramingRequired;
-  if (opensFramingGate) implementationFramingRequired = true;
-  if (closesFramingGate) implementationFramingRequired = false;
-
-  let verificationRequired = state.verificationRequired;
-  if (route.owner === "direct" && event.changedArtifacts) verificationRequired = true;
-  if (route.owner === "verify" && event.status === "resolved") verificationRequired = false;
-
-  return {
-    ...state,
-    activeRoute: undefined,
-    lastJudgment: judgment,
-    pendingQuestions: pending,
-    focusedQuestionId: pending.some((question) => question.id === state.focusedQuestionId)
-      ? state.focusedQuestionId
-      : undefined,
-    implementationFramingRequired,
-    verificationRequired,
-  };
-}
-
 function isObject(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object";
 }
@@ -188,7 +176,12 @@ function isMode(value: unknown): value is DeveloperMode {
 }
 
 function isJudgmentStatus(value: unknown): value is JudgmentStatus {
-  return value === "resolved" || value === "needs-evidence" || value === "not-applicable" || value === "blocked";
+  return (
+    value === "resolved" ||
+    value === "needs-evidence" ||
+    value === "not-applicable" ||
+    value === "blocked"
+  );
 }
 
 function isDirectExecutionProfile(value: unknown): value is DirectExecutionProfile {
@@ -211,31 +204,158 @@ function parseDirectStep(value: unknown): DirectStepContract | undefined {
   };
 }
 
+function parseRouteAlternative(value: unknown): RouteAlternative | undefined {
+  if (!isObject(value) || typeof value.owner !== "string" || typeof value.reason !== "string") {
+    return undefined;
+  }
+  return { owner: value.owner, reason: value.reason };
+}
+
+function isQuestionResolutionOwner(value: unknown): value is QuestionResolutionOwner {
+  return value === "agent" || value === "user" || value === "environment" || value === "unknown";
+}
+
+function isQuestionGate(value: unknown): value is QuestionGate {
+  return value === "none" || value === "before-direct" || value === "before-completion";
+}
+
+function isQuestionUpdateStatus(value: unknown): value is QuestionUpdateStatus {
+  return (
+    value === "resolved" || value === "not-applicable" || value === "open" || value === "blocked"
+  );
+}
+
+const RESPONSE_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function requiredResponseText(value: unknown, maxChars: number): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim();
+  return text && text.length <= maxChars ? text : undefined;
+}
+
+function optionalResponseText(value: unknown): string | undefined | null {
+  if (value === undefined) return undefined;
+  return requiredResponseText(value, MAX_RESPONSE_TEXT_CHARS) ?? null;
+}
+
+function parseChoiceResponseOption(
+  value: unknown,
+  seenValues: Set<string>,
+): ChoiceResponseOption | undefined {
+  if (!isObject(value)) return undefined;
+  const optionValue = requiredResponseText(value.value, MAX_RESPONSE_IDENTIFIER_CHARS);
+  const label = requiredResponseText(value.label, MAX_RESPONSE_TEXT_CHARS);
+  const description = optionalResponseText(value.description);
+  const detailPrompt = optionalResponseText(value.detailPrompt);
+  if (!optionValue || !RESPONSE_IDENTIFIER.test(optionValue)) return undefined;
+  if (seenValues.has(optionValue) || !label) return undefined;
+  if (description === null || detailPrompt === null) return undefined;
+  seenValues.add(optionValue);
+  return { value: optionValue, label, description, detailPrompt };
+}
+
+function parseChoiceResponseField(
+  value: unknown,
+  seenIds: Set<string>,
+): ChoiceResponseField | undefined {
+  if (!isObject(value) || !Array.isArray(value.options)) return undefined;
+  const id = requiredResponseText(value.id, MAX_RESPONSE_IDENTIFIER_CHARS);
+  const prompt = requiredResponseText(value.prompt, MAX_RESPONSE_TEXT_CHARS);
+  const description = optionalResponseText(value.description);
+  if (!id || !RESPONSE_IDENTIFIER.test(id)) return undefined;
+  if (seenIds.has(id) || !prompt || description === null) return undefined;
+  if (value.options.length < 2 || value.options.length > MAX_RESPONSE_OPTIONS) return undefined;
+
+  seenIds.add(id);
+  const seenValues = new Set<string>();
+  const options: ChoiceResponseOption[] = [];
+  for (const rawOption of value.options) {
+    const option = parseChoiceResponseOption(rawOption, seenValues);
+    if (!option) return undefined;
+    options.push(option);
+  }
+  return { id, prompt, description, options };
+}
+
+export function parseChoiceResponseSpec(value: unknown): ChoiceResponseSpec | undefined {
+  if (!isObject(value) || value.kind !== "choice-form" || !Array.isArray(value.fields)) {
+    return undefined;
+  }
+  if (value.fields.length === 0 || value.fields.length > MAX_RESPONSE_FIELDS) {
+    return undefined;
+  }
+  const seenIds = new Set<string>();
+  const fields: ChoiceResponseField[] = [];
+  for (const rawField of value.fields) {
+    const field = parseChoiceResponseField(rawField, seenIds);
+    if (!field) return undefined;
+    fields.push(field);
+  }
+  return { kind: "choice-form", fields };
+}
+
 function parsePendingQuestion(value: unknown): PendingQuestion | undefined {
   if (!isObject(value)) return undefined;
   if (
     typeof value.id !== "string" ||
     typeof value.question !== "string" ||
-    (value.status !== "needs-evidence" && value.status !== "blocked") ||
+    (value.status !== "open" && value.status !== "blocked" && value.status !== "needs-evidence") ||
     typeof value.sourceRouteId !== "string"
   ) {
     return undefined;
   }
+  const legacyBlocked = value.status === "blocked";
+  let resolutionOwner: QuestionResolutionOwner = legacyBlocked ? "unknown" : "agent";
+  if (isQuestionResolutionOwner(value.resolutionOwner)) resolutionOwner = value.resolutionOwner;
+  let gate: QuestionGate = legacyBlocked ? "before-completion" : "none";
+  if (isQuestionGate(value.gate)) gate = value.gate;
+  const resolutionCriteria =
+    typeof value.resolutionCriteria === "string"
+      ? value.resolutionCriteria
+      : `Obtain evidence that settles: ${value.question}`;
+  const context = typeof value.context === "string" ? value.context.trim() || undefined : undefined;
+  const responseSpec =
+    resolutionOwner === "user" ? parseChoiceResponseSpec(value.responseSpec) : undefined;
   return {
     id: value.id,
     question: value.question,
-    status: value.status,
+    context,
+    responseSpec,
+    status: legacyBlocked ? "blocked" : "open",
+    resolutionOwner,
+    gate,
+    resolutionCriteria,
     sourceRouteId: value.sourceRouteId,
   };
 }
 
+function parseQuestionUpdate(value: unknown): QuestionUpdate | undefined {
+  if (
+    !isObject(value) ||
+    typeof value.questionId !== "string" ||
+    !isQuestionUpdateStatus(value.status) ||
+    typeof value.result !== "string" ||
+    !isStringArray(value.basis)
+  ) {
+    return undefined;
+  }
+  return {
+    questionId: value.questionId,
+    status: value.status,
+    result: value.result,
+    basis: value.basis,
+  };
+}
+
 export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefined {
   if (!isObject(value)) return undefined;
   if (
     value.protocol !== PROTOCOL &&
     value.protocol !== PREVIOUS_PROTOCOL &&
+    value.protocol !== OLDER_PROTOCOL &&
     value.protocol !== LEGACY_PROTOCOL
-  ) return undefined;
+  )
+    return undefined;
 
   if (value.kind === "mode") {
     if (!isMode(value.mode)) return undefined;
@@ -243,7 +363,11 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
   }
 
   if (value.kind === "focus") {
-    if (value.protocol !== PROTOCOL || typeof value.questionId !== "string") return undefined;
+    if (
+      (value.protocol !== PROTOCOL && value.protocol !== PREVIOUS_PROTOCOL) ||
+      typeof value.questionId !== "string"
+    )
+      return undefined;
     return { protocol: PROTOCOL, kind: "focus", questionId: value.questionId };
   }
 
@@ -254,6 +378,8 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
       typeof value.owner !== "string" ||
       typeof value.reason !== "string" ||
       !isStringArray(value.knownEvidence) ||
+      (value.consideredAlternatives !== undefined &&
+        !Array.isArray(value.consideredAlternatives)) ||
       (value.targetQuestionId !== undefined && typeof value.targetQuestionId !== "string") ||
       (value.methodLocation !== undefined && typeof value.methodLocation !== "string") ||
       (value.executionProfile !== undefined && !isDirectExecutionProfile(value.executionProfile)) ||
@@ -261,6 +387,10 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
     ) {
       return undefined;
     }
+    const consideredAlternatives = Array.isArray(value.consideredAlternatives)
+      ? value.consideredAlternatives.map(parseRouteAlternative)
+      : [];
+    if (consideredAlternatives.some((alternative) => !alternative)) return undefined;
     return {
       protocol: PROTOCOL,
       kind: "route",
@@ -269,6 +399,7 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
       owner: value.owner,
       reason: value.reason,
       knownEvidence: value.knownEvidence,
+      consideredAlternatives: consideredAlternatives as RouteAlternative[],
       targetQuestionId: value.targetQuestionId,
       methodLocation: value.methodLocation,
       executionProfile: value.executionProfile,
@@ -303,9 +434,13 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
       openedQuestions: value.openQuestions.map((question, index) => ({
         id: `question:${value.routeId}:legacy:${index + 1}`,
         question,
-        status: "needs-evidence",
+        status: "open",
+        resolutionOwner: "agent",
+        gate: "none",
+        resolutionCriteria: `Obtain evidence that settles: ${question}`,
         sourceRouteId: String(value.routeId),
       })),
+      questionUpdates: [],
       artifacts: value.artifacts,
       changedArtifacts: false,
     };
@@ -314,6 +449,12 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
   if (!Array.isArray(value.openedQuestions)) return undefined;
   const openedQuestions = value.openedQuestions.map(parsePendingQuestion);
   if (openedQuestions.some((question) => !question)) return undefined;
+  if (value.questionUpdates !== undefined && !Array.isArray(value.questionUpdates))
+    return undefined;
+  const questionUpdates = Array.isArray(value.questionUpdates)
+    ? value.questionUpdates.map(parseQuestionUpdate)
+    : [];
+  if (questionUpdates.some((update) => !update)) return undefined;
   return {
     protocol: PROTOCOL,
     kind: "judgment",
@@ -324,6 +465,7 @@ export function normalizeDeveloperEvent(value: unknown): DeveloperEvent | undefi
     result: value.result,
     basis: value.basis,
     openedQuestions: openedQuestions as PendingQuestion[],
+    questionUpdates: questionUpdates as QuestionUpdate[],
     artifacts: value.artifacts,
     changedArtifacts: typeof value.changedArtifacts === "boolean" ? value.changedArtifacts : false,
   };

package/extensions/tool-policy.ts

@@ -1,6 +1,12 @@
 import type { DeveloperMode } from "./state.ts";
 
-const MUTATION_TOOL_NAMES = new Set(["edit", "write", "bash"]);
+export type ControlledToolCapability = "execute" | "mutate";
+
+const CONTROLLED_BUILTIN_CAPABILITIES = new Map<string, ControlledToolCapability>([
+  ["bash", "execute"],
+  ["edit", "mutate"],
+  ["write", "mutate"],
+]);
 
 export interface ToolMetadataLike {
   name: string;
@@ -16,46 +22,69 @@ export interface ToolPolicyResult {
   memory: ToolPolicyMemory;
 }
 
-export function builtinMutationToolNames(tools: ToolMetadataLike[]): Set<string> {
-  return new Set(
-    tools
-      .filter((tool) => tool.sourceInfo.source === "builtin" && MUTATION_TOOL_NAMES.has(tool.name))
-      .map((tool) => tool.name),
-  );
+export interface ProtocolToolAccess {
+  canExecute: boolean;
+  canMutate: boolean;
+  hasBeforeDirectGate: boolean;
+}
+
+export function builtinControlledToolCapabilities(
+  tools: ToolMetadataLike[],
+): Map<string, ControlledToolCapability> {
+  const result = new Map<string, ControlledToolCapability>();
+  for (const tool of tools) {
+    if (tool.sourceInfo.source !== "builtin") continue;
+    const capability = CONTROLLED_BUILTIN_CAPABILITIES.get(tool.name);
+    if (capability) result.set(tool.name, capability);
+  }
+  return result;
+}
+
+export function isControlledToolAllowed(input: {
+  mode: DeveloperMode;
+  capability: ControlledToolCapability;
+  access: ProtocolToolAccess;
+}): boolean {
+  if (input.mode === "off") return true;
+
+  if (input.access.hasBeforeDirectGate) {
+    if (input.capability === "mutate") return false;
+    return input.access.canExecute && !input.access.canMutate;
+  }
+
+  if (input.mode === "on") return true;
+  if (input.capability === "execute") return input.access.canExecute;
+  return input.access.canMutate;
 }
 
 export function reconcileProtocolTools(input: {
   activeTools: string[];
   allTools: ToolMetadataLike[];
   mode: DeveloperMode;
-  directRouteOpen: boolean;
+  access: ProtocolToolAccess;
   protocolTools: readonly string[];
   memory: ToolPolicyMemory;
 }): ToolPolicyResult {
   const active = new Set(input.activeTools);
-  const mutationBuiltins = builtinMutationToolNames(input.allTools);
+  const controlledBuiltins = builtinControlledToolCapabilities(input.allTools);
   const withheld = new Set(
-    [...input.memory.withheldBuiltins].filter((name) => mutationBuiltins.has(name)),
+    [...input.memory.withheldBuiltins].filter((name) => controlledBuiltins.has(name)),
   );
 
-  if (input.mode === "strict") {
+  if (input.mode === "off") {
+    for (const name of withheld) active.add(name);
+    withheld.clear();
+    for (const tool of input.protocolTools) active.delete(tool);
+  } else {
     for (const tool of input.protocolTools) active.add(tool);
-
-    if (input.directRouteOpen) {
-      for (const tool of withheld) active.add(tool);
-    } else {
-      for (const tool of mutationBuiltins) {
-        if (active.delete(tool)) withheld.add(tool);
+    for (const [name, capability] of controlledBuiltins) {
+      const allowed = isControlledToolAllowed({ mode: input.mode, capability, access: input.access });
+      if (allowed) {
+        if (withheld.delete(name)) active.add(name);
+      } else if (active.delete(name)) {
+        withheld.add(name);
       }
     }
-  } else {
-    for (const tool of withheld) active.add(tool);
-    withheld.clear();
-
-    for (const tool of input.protocolTools) {
-      if (input.mode === "on") active.add(tool);
-      else active.delete(tool);
-    }
   }
 
   return {