agent-nuvira 3.1.3 → 3.2.0

package/dist/learning/autonomy-policy.d.ts

@@ -0,0 +1,334 @@
+/**
+ * Autonomy policy — may the agent decide for itself, or must it ask?
+ * (enterprise-grade hardening, G11.)
+ *
+ * WHY THIS EXISTS (the WhatsApp story audit + the "manual cadence" complaint):
+ * Two failure modes sit on opposite sides of the same missing rule.
+ *
+ *   1. STALLING ON AN ANSWERABLE QUESTION. The story session asked/implied
+ *      decisions it could have made itself ("should I keep going?", "which
+ *      file?"), and every one of those turned into a turn that ended without
+ *      delivered work. An agent that consults on a choice it can make is not
+ *      careful — it is a bottleneck, and it is how 32 minutes produced zero
+ *      words.
+ *   2. DECIDING SOMETHING THAT WAS NEVER ITS CALL. The opposite failure, where
+ *      an agent silently picks a direction the user cared about (which
+ *      provider to bill, whether to overwrite existing work, what to delete).
+ *
+ * The enterprise behaviour is a POLICY, not a mood: decide by default, consult
+ * only when the decision is (a) genuinely the user's, (b) not implied by the
+ * ask, (c) irreversible or expensive to get wrong, and (d) has no sensible
+ * default. Everything else is the agent's job.
+ *
+ * This module is deterministic and LLM-free on purpose: it is the guard rail
+ * around a model's own "should I ask?" instinct, which skews towards asking.
+ */
+/** How much damage a wrong choice does. */
+export type DecisionImpact = 'low' | 'medium' | 'high';
+/** One decision the agent is facing. */
+export interface DecisionRequest {
+    /** What is being decided, phrased for the user (used verbatim if we consult). */
+    question: string;
+    /** Candidate answers, best-first. Empty means the answer is free-form. */
+    options?: string[];
+    /** What the agent would pick on its own. Presence = "a sensible default exists". */
+    defaultChoice?: string;
+    /** How much a wrong pick costs. Defaults to `medium`. */
+    impact?: DecisionImpact;
+    /**
+     * Can the choice be undone cheaply? Overwriting a file that exists, deleting
+     * data, spending money and publishing are NOT reversible; picking a library
+     * or a layout usually is.
+     */
+    reversible?: boolean;
+    /**
+     * Does the original ask already imply this choice? "a web-based book with
+     * voice narration" has already answered "should it have audio?" and "should
+     * it be a website?" — re-asking is a non-delivery dressed as diligence.
+     */
+    impliedByAsk?: boolean;
+    /** Minutes of rework a wrong choice would add. */
+    reworkMinutes?: number;
+    /**
+     * True when the run cannot continue at all without an answer.
+     *
+     * A non-blocking decision is a PREFERENCE: the agent proceeds with its
+     * default and the user can redirect later, so consulting would only add a
+     * round trip with no benefit.
+     */
+    blocking?: boolean;
+}
+/** The ruling. */
+export interface DecisionVerdict {
+    action: 'proceed' | 'consult';
+    /** The choice to take when proceeding. */
+    choice?: string;
+    /** Why — recorded in the trace/log so the call is auditable, not vibes. */
+    reason: string;
+}
+/**
+ * Rework above this many minutes makes a defaulted choice expensive enough to
+ * be worth a round trip even when the choice is reversible.
+ */
+export declare const REWORK_CONSULT_THRESHOLD_MINUTES = 45;
+/**
+ * Decide whether the agent proceeds on its own or asks the user.
+ *
+ * Order matters. The cheap, obviously-ours cases are settled first so that a
+ * later rule can never turn an easy call into a consultation:
+ *
+ *  1. NOT BLOCKING, NOT HIGH-IMPACT -> proceed. Nothing is waiting on an
+ *     answer, and the user can redirect at any time. Asking is pure latency.
+ *  2. THE ASK ALREADY SAID SO -> proceed with the implied choice. Re-asking a
+ *     question the user answered in their own request is the "cheap shortcut"
+ *     in reverse: it looks like diligence and delivers nothing.
+ *  3. A BLOCKING, HIGH-IMPACT, IRREVERSIBLE DECISION WITH NO DEFAULT -> this is
+ *     the user's call. Consult — with a defaulted recommendation, so the reply
+ *     is a one-word confirmation rather than an essay.
+ *  4. OTHERWISE -> proceed with the default, unless the rework a wrong pick
+ *     would cost is large enough to justify asking (rule 5).
+ *  5. EXPENSIVE + NO DEFAULT -> consult.
+ *
+ * A blocking decision with a sensible default proceeds. That is the whole
+ * point of the policy: "which file should I write to" has a default (the one
+ * named in the ask, or a predictable one), so it must never stop a run.
+ */
+export declare function decideAutonomously(request: DecisionRequest): DecisionVerdict;
+/** The ruling on whether the user's own request authorized file writes. */
+export interface WriteAuthorization {
+    authorized: boolean;
+    /** Why — recorded so the judgment is auditable rather than a vibe. */
+    reason: string;
+}
+/**
+ * Does this request authorize the agent to CREATE files?
+ *
+ * This is the input the write gate was missing. The gate was binary — "confirm
+ * or refuse" — with no notion of a request that had ALREADY authorized the
+ * work, so an unattended run whose ask was literally "write a 12 page story"
+ * stopped to ask "Do you want me to create the files?". That is not caution;
+ * it is the manual cadence, and over a chat surface it is a round trip that
+ * produces nothing.
+ *
+ * Evidence order: an explicit confirmation of proposed work, then a
+ * continuation, then a named destination path, then a creation verb applied to
+ * a file-shaped deliverable. An analysis/interrogative opener vetoes the last
+ * two, so "explain how to write a story to a file" stays a question.
+ *
+ * Deliberately conservative: anything it does not recognise is NOT authorized,
+ * which keeps today's confirm-or-refuse gate exactly as strict as it was.
+ */
+export declare function requestAuthorizesWrites(request: string): WriteAuthorization;
+/**
+ * A request that asks for the work to be recorded in git history.
+ *
+ * `git commit` was gated behind `confirm:true` "after the user approved via
+ * ask_user" — but when the user's ask IS "commit these changes", they have
+ * already approved and the gate is a round trip in the most common dev flow.
+ * Like every other rule here, the evidence has to come from the request text.
+ *
+ * A NEGATED commit ("don't commit yet") is explicitly not a request for one,
+ * and an analysis opener ("how do I commit?") is asking ABOUT it.
+ */
+export declare function requestRequestsCommit(request: string): boolean;
+/**
+ * Does the request name THIS file?
+ *
+ * The evidence an edit gate needs: "fix calc.ts" names the file, "update the
+ * README" names it. Compared on the BASENAME too, because a request says
+ * `calc.ts` for `src/lib/calc.ts` — that is how people actually write, and
+ * requiring the full path would make the rule dead on arrival.
+ *
+ * Deliberately literal (the basename or the path, as a whole word): a fuzzy
+ * match would let "write a story" claim `story.md` and turn a create into an
+ * unreviewed overwrite.
+ */
+export declare function requestNamesPath(request: string, path: string): boolean;
+/**
+ * Above this share of a file being rewritten, an edit is a REPLACEMENT rather
+ * than a surgical change — and replacing most of what exists is the user's call,
+ * for the same reason write_file's overwrite case is.
+ */
+export declare const EDIT_SURGICAL_MAX_FRACTION = 0.5;
+/**
+ * Is this edit surgical — does it preserve most of the file it touches?
+ *
+ * The measurable line between "a fix inside a file" and "a rewrite of the
+ * file". A surgical edit is the iteration the verify loop is built around
+ * (run → read the failure → edit → re-run); a rewrite is a judgment call.
+ */
+export declare function isSurgicalEdit(fileChars: number, oldChars: number, newChars: number): boolean;
+/** Is this ONE sentence a request for permission / a proposal to do the work? */
+export declare function isPermissionSeekingSentence(sentence: string): boolean;
+/**
+ * True when the answer CLOSES by asking permission to do work, rather than
+ * delivering it.
+ *
+ * The distinction that matters: "should I proceed?" is a stall, while "which
+ * title do you prefer?" is a genuine question. This detector only claims the
+ * permission-seeking half — callers AND it with an authorization verdict, so a
+ * question about work that was never authorized is untouched.
+ *
+ * Only the closing sentences are judged: a question mid-answer followed by the
+ * actual deliverable is narration, not a stall.
+ */
+export declare function detectPermissionSeeking(content: string): boolean;
+/**
+ * Remove the trailing permission-seeking sentences from an answer, keeping
+ * everything before them VERBATIM (deliverables are prose — re-joining split
+ * sentences would reformat the work itself).
+ *
+ * Used when a turn is nudged to proceed: the real work in that step must stay
+ * a candidate answer, but the question around it must not be what the user is
+ * handed — otherwise a longer "…Do you want me to…?" outranks a shorter, real
+ * follow-up answer under the loop's longest-substantive rule.
+ */
+export declare function stripTrailingPermissionSeek(content: string): string;
+/**
+ * Actions that cannot be undone by re-running the agent. A question that names
+ * one of these is NEVER treated as reflexive permission-seeking, because the
+ * user genuinely has to own it.
+ */
+export declare const IRREVERSIBLE_ACTION_RE: RegExp;
+/**
+ * Should a state-changing write go ahead, or is it the user's call?
+ *
+ * The scoped rule (from the audit): creating a file the request asked for, at a
+ * path where NOTHING EXISTS, cannot destroy anything and is undone by deleting
+ * the file — so making the user confirm it is pure latency. Everything else
+ * keeps the gate it has today:
+ *
+ *   - a request that never authorized file creation (gate stays as strict);
+ *   - overwriting content that already exists (a re-run cannot recover it).
+ *
+ * Note the asymmetry is deliberate and load-bearing: the safety property the
+ * original gate protected (never clobber existing work without a human) is
+ * untouched, while the property it lacked (do not stall on work the user
+ * already ordered) is added.
+ */
+export interface WriteConfirmationRequest {
+    /** Tool being attempted (`write_file`, `edit_file`, …) — for the audit line. */
+    tool: string;
+    /** The target path, already workspace-relative for display. */
+    path: string;
+    /** Does content already exist at the target, so this write REPLACES it? */
+    exists: boolean;
+    /** The verdict from {@link requestAuthorizesWrites} for the current request. */
+    authorizedByRequest: boolean;
+}
+/** The ruling on a state-changing write. */
+export interface WriteConfirmationVerdict {
+    action: 'proceed' | 'ask';
+    reason: string;
+}
+/** Decide whether a state-changing write proceeds or asks the user. */
+export declare function decideWriteConfirmation(request: WriteConfirmationRequest): WriteConfirmationVerdict;
+/**
+ * What kind of change an action makes to the world.
+ *
+ * Every confirmation-gated tool was asking the same question — "has the user
+ * authorized this?" — with no way to answer it, so each one could only refuse
+ * and route the model to `ask_user`. Naming the classes makes the rule table
+ * explicit and keeps the two classes that must NEVER run autonomously in one
+ * place instead of four.
+ *
+ *   - `create`      adds something that did not exist;
+ *   - `modify`      changes content that already exists (a surgical edit, a
+ *                   workspace mutation);
+ *   - `local-state` this machine's repo/process/service state — recoverable by
+ *                   re-running or by starting the service again;
+ *   - `external`    leaves this machine, or is seen or billed by someone else;
+ *   - `destructive` removes or irrecoverably replaces what already exists.
+ */
+export type StateChangeClass = 'create' | 'modify' | 'local-state' | 'external' | 'destructive';
+/** One gated state change, with the evidence the acting tool could measure. */
+export interface StateChangeRequest {
+    /** Tool being attempted (`edit_file`, `run_terminal`, …) — for the audit line. */
+    tool: string;
+    /** One line describing what will happen, phrased for the refusal text. */
+    action: string;
+    /** Which kind of change this is. */
+    changeClass: StateChangeClass;
+    /**
+     * Does the user's OWN REQUEST name this specific action or target (the file,
+     * the command, the intent)? The strongest evidence short of a confirmation.
+     */
+    namedByRequest?: boolean;
+    /**
+     * A tool-MEASURED property that makes the change recoverable — a surgical
+     * edit that preserves most of the file, a workspace-local install.
+     */
+    recoverable?: boolean;
+    /**
+     * Did the request authorize this class of work at all
+     * ({@link requestAuthorizesWrites})? Absent evidence means NOT authorized.
+     */
+    authorizedByRequest?: boolean;
+}
+/**
+ * Decide whether a state-changing action proceeds or asks the user.
+ *
+ * Order matters, and the two never-autonomous classes are settled first so no
+ * later rule can turn them into an autonomous action:
+ *
+ *   1. DESTRUCTIVE -> ask. Permanent, so it stays the user's call even when
+ *      they named it: one round trip is cheap, being wrong is not.
+ *   2. EXTERNAL -> ask. Someone else sees it, or it is billed.
+ *   3. NEITHER AUTHORIZED NOR NAMED -> ask. This is the original strictness
+ *      (and the no-loop-context default) untouched.
+ *   4. NAMED BY THE REQUEST -> proceed. The user's own words are the
+ *      authorization; re-asking is a round trip with no new information.
+ *   5. AUTHORIZED + RECOVERABLE -> proceed. The work was ordered and the change
+ *      cannot strand the user.
+ *   6. OTHERWISE -> ask. Authorized but neither named nor measurably
+ *      recoverable is exactly the case where a surprise is possible.
+ */
+export declare function decideStateChange(request: StateChangeRequest): WriteConfirmationVerdict;
+/**
+ * Confirmation-gated CLI intents that cannot be undone by re-running the
+ * agent: irreversible data loss, or an effect outside this machine.
+ *
+ * These keep their gate even when the request names them. One round trip is a
+ * small price for a decision that cannot be taken back.
+ */
+export declare const IRREVERSIBLE_CLI_INTENTS: ReadonlySet<string>;
+/**
+ * Confirmation-gated CLI intents that ARE recoverable: a service that can be
+ * started again, config that can be re-added, a cache that rebuilds, a skill
+ * that reinstalls.
+ *
+ * These proceed when the user's own request resolves to the exact command. The
+ * manifest flag exists because the ACTION is stateful, not because the user
+ * needs to approve what they just asked for.
+ */
+export declare const RECOVERABLE_CLI_INTENTS: ReadonlySet<string>;
+/**
+ * Decide a confirmation-gated CLI intent.
+ *
+ * Note what this does NOT consult: {@link requestAuthorizesWrites}. That verdict
+ * answers "did the request ask for files to be created" — the wrong lens for a
+ * system ask like "stop the dashboard", which would read as unauthorized and
+ * defeat the whole rule. The evidence that matters here is whether the USER'S
+ * OWN WORDS resolve to this exact command (the caller resolves them with the
+ * same router, so the tool's ask and the user's ask are compared like for like).
+ */
+export declare function decideCliIntentConfirmation(request: {
+    intent: string;
+    /** Does the user's own request resolve to this exact command? */
+    namedByRequest: boolean;
+}): WriteConfirmationVerdict;
+/**
+ * The line shown when the agent decides something on the user's behalf.
+ *
+ * Reported, never silent: the user must be able to see and reverse a judgment
+ * call. A decision that is invisible is indistinguishable from a bug.
+ */
+export declare function autonomouslyDecidedLine(question: string, choice: string, reason: string): string;
+/**
+ * The line shown when the agent genuinely cannot decide for the user.
+ *
+ * Deliberately shaped for a one-word reply: the recommendation and the
+ * fallback are both named, so the user is confirming rather than composing.
+ */
+export declare function consultLine(request: DecisionRequest, verdict: DecisionVerdict): string;
+//# sourceMappingURL=autonomy-policy.d.ts.map

package/dist/learning/autonomy-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autonomy-policy.d.ts","sourceRoot":"","sources":["../../src/learning/autonomy-policy.ts"],"names":[],"mappings":"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"}