@pedrocivita/tocket 2.4.0 → 2.6.3

package/dist/utils/decide.d.ts

@@ -0,0 +1,178 @@
+/** Generic Choice/Noul decisions. File-first; writes only under `.context/decisions/`. */
+import { type JevQuestion } from "./jev.js";
+export declare const DECIDE_SCHEMA = "tocket.decide/v0";
+export declare const DECISIONS_DIR = ".context/decisions";
+export declare const DECISIONS_README = "README.md";
+export declare const STUB_MODEL = "stub-v0";
+/** Codila chief.py default: only route research/write at or above this confidence. */
+export declare const DEFAULT_CONFIDENCE_THRESHOLD = 0.85;
+export declare const QUEUE_DESTINATIONS: readonly ["research", "write", "review"];
+export declare const HIGH_CONFIDENCE_ROUTES: readonly ["research", "write"];
+export declare const BOUNDED_FORKS: readonly ["agent", "model", "tool", "action", "human"];
+export declare const DECIDE_LOOP = "state-questions-action-verify";
+export declare const RANK_WIDE_MIN = 5;
+/** Well-known Choice names for the file-first tool-risk gate (AutoMode pattern, not LangChain APIs). */
+export declare const TOOL_GATE_NAMES: readonly ["tool_gate", "action_gate"];
+export declare const TOOL_GATE_OPTIONS: readonly ["allow", "block", "ask"];
+export type QueueDestination = (typeof QUEUE_DESTINATIONS)[number];
+export type BoundedFork = (typeof BOUNDED_FORKS)[number];
+export type DecideMode = "active" | "shadow" | "dry-run";
+export type DecideSource = "jev" | "stub";
+export type DecideSemantics = "handoff" | "log-only";
+export type DecideHandoffStatus = "queued" | "logged";
+export type DecidePrimitive = "choice" | "noul" | "score";
+export type ToolGate = (typeof TOOL_GATE_OPTIONS)[number];
+export type ToolGateName = (typeof TOOL_GATE_NAMES)[number];
+export interface DecideChoiceSpec {
+    name: string;
+    options: string[];
+}
+export interface DecideNoulSpec {
+    name: string;
+}
+export interface DecideScoreSpec {
+    name: string;
+    min: number;
+    max: number;
+}
+export interface DecideChoiceAnswer {
+    type: "choice";
+    choice: string;
+    confidence: number;
+    rationale: string;
+    probabilities?: Record<string, number>;
+}
+export interface DecideNoulAnswer {
+    type: "noul";
+    noul: number;
+    confidence: number;
+    rationale: string;
+}
+export interface DecideScoreAnswer {
+    type: "score";
+    score: number;
+    confidence: number;
+    rationale: string;
+}
+export type DecideAnswer = DecideChoiceAnswer | DecideNoulAnswer | DecideScoreAnswer;
+export interface DecideRecord {
+    schema: typeof DECIDE_SCHEMA;
+    id: string;
+    generated_at: string;
+    mode: DecideMode;
+    source: DecideSource;
+    model: string;
+    /** Codila-style router: selected option (first Choice). */
+    choice: string | null;
+    confidence: number;
+    /** Queue hint: research | write | review. Low-confidence research/write becomes review. */
+    destination: QueueDestination;
+    gated: boolean;
+    /**
+     * Tool-risk gate from a `tool_gate` / `action_gate` Choice (`allow|block|ask`).
+     * Null when the handoff has no gate question. Independent of Codila `gated`.
+     */
+    tool_gate: ToolGate | null;
+    confidence_threshold: number;
+    /** handoff = workers may consume; log-only = shadow/dry-run (Tocket does not run workers). */
+    semantics: DecideSemantics;
+    status: DecideHandoffStatus;
+    /** Always false: Jev decides; LLMs create; agents act. This CLI only writes a file. */
+    executes: false;
+    loop: typeof DECIDE_LOOP;
+    fork: BoundedFork;
+    primitives: DecidePrimitive[];
+    batched: boolean;
+    rank_wide: boolean;
+    narrow: string | null;
+    state_summary: string;
+    state: unknown;
+    questions: Record<string, JevQuestion>;
+    answers: Record<string, DecideAnswer>;
+}
+export interface RunDecideOptions {
+    cwd: string;
+    state?: string;
+    fromPath?: string;
+    choices?: string[];
+    nouls?: string[];
+    scores?: string[];
+    fork?: string;
+    dryRun?: boolean;
+    shadow?: boolean;
+    id?: string;
+    confidenceThreshold?: number;
+    apiKey?: string | null;
+    now?: () => string;
+    fetchImpl?: typeof fetch;
+}
+export declare class DecideError extends Error {
+    constructor(message: string);
+}
+export declare function parseChoiceSpec(spec: string): DecideChoiceSpec;
+export declare function parseNoulSpec(spec: string): DecideNoulSpec;
+export declare function parseScoreSpec(spec: string): DecideScoreSpec;
+export declare function parseFork(raw?: string): BoundedFork;
+export declare function choiceCriterion(option: string): string;
+export declare function isQueueDestination(value: string): value is QueueDestination;
+export declare function isHighConfidenceRoute(value: string): boolean;
+export declare function isToolGateName(name: string): boolean;
+export declare function isToolGate(value: string | null | undefined): value is ToolGate;
+export declare function parseToolGate(value: unknown): ToolGate | null;
+/** Read a well-known `tool_gate` / `action_gate` Choice from answers. */
+export declare function extractToolGate(answers: Record<string, DecideAnswer>): ToolGate | null;
+export declare function resolveRecordToolGate(record: {
+    tool_gate?: ToolGate | null;
+    answers?: Record<string, DecideAnswer>;
+}): ToolGate | null;
+export declare function toolGateRefusesApply(gate: ToolGate | null): boolean;
+export declare function parseConfidenceThreshold(raw?: string | number): number;
+export declare function primaryChoice(answers: Record<string, DecideAnswer>): {
+    choice: string | null;
+    confidence: number;
+};
+/** Codila gate: research/write only when confidence >= threshold; otherwise review. */
+export declare function resolveDestination(choice: string | null, confidence: number, threshold?: number, fork?: BoundedFork): {
+    destination: QueueDestination;
+    gated: boolean;
+};
+export declare function resolveSemantics(mode: DecideMode): {
+    semantics: DecideSemantics;
+    status: DecideHandoffStatus;
+};
+export declare function slugId(value: string): string;
+export declare function fileTimestamp(iso: string): string;
+export declare function summarizeState(state: unknown): string;
+export declare function stateBlob(state: unknown): string;
+export declare function parseStateInput(raw: string): unknown;
+export declare function loadState(options: {
+    state?: string;
+    fromPath?: string;
+}): unknown;
+export declare function buildQuestions(choices: DecideChoiceSpec[], nouls: DecideNoulSpec[], scores?: DecideScoreSpec[]): Record<string, JevQuestion>;
+export declare function stubChoice(name: string, options: string[], state: unknown): DecideChoiceAnswer;
+export declare function stubNoul(_name: string, state: unknown): DecideNoulAnswer;
+export declare function stubScore(name: string, min: number, max: number, state: unknown): DecideScoreAnswer;
+export declare function stubAnswers(questions: Record<string, JevQuestion>, state: unknown): Record<string, DecideAnswer>;
+export declare function isInsideContext(cwd: string, targetPath: string): boolean;
+export declare function decisionOutputPath(cwd: string, generatedAt: string, id: string, destination?: QueueDestination): string;
+export declare function defaultDecisionId(choices: DecideChoiceSpec[], nouls: DecideNoulSpec[], scores?: DecideScoreSpec[]): string;
+export declare function listPrimitives(questions: Record<string, JevQuestion>): DecidePrimitive[];
+export declare function choiceOptionCount(questions: Record<string, JevQuestion>): number;
+export declare function resolveDecideMode(options: {
+    dryRun?: boolean;
+    shadow?: boolean;
+    apiKey?: string;
+}): {
+    useLive: boolean;
+    mode: DecideMode;
+};
+export declare function prettyDecideJson(value: unknown): string;
+export declare function decisionsReadmeStub(): string;
+export declare function parseDecideRecord(raw: string): DecideRecord;
+export declare function formatDecideSummary(record: DecideRecord, relPath: string): string;
+export declare function runDecide(options: RunDecideOptions): Promise<{
+    record: DecideRecord;
+    outPath: string;
+}>;
+export declare function toRepoRelative(cwd: string, outPath: string): string;