trellis/dist/vcs/authority.d.ts

Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications

/**
 * Harness-facing tool decision authority.
 *
 * The kernel owns the RULES; harnesses own the PLUMBING. A harness tool
 * executor calls `canToolRun()` synchronously before a tool executes; the
 * returned decision is final. No policy logic belongs in the harness — this
 * module is the single rulebook (see docs/planning/trellis-tui-fork-cycle.md).
 *
 * Prevention is layered: shell hygiene (zsh alias / PATH shim) covers the
 * human's terminal, this authority covers harness tools, and the op-log
 * watcher detects anything that slips past both. The kernel is not an
 * execution point — it cannot stop a raw `git reset`; it makes destruction
 * hard and unjournaled state unpromotable.
 */
export type ToolDecision = {
    allow: true;
} | {
    allow: false;
    deny: true;
    reason: string;
    /** The sanctioned alternative to suggest (e.g. `trellis lane promote`). */
    redirect?: string;
} | {
    allow: false;
    prompt: true;
    message: string;
    confirmLabel: string;
};
export interface ToolInvocation {
    /** Harness tool name: `bash`, `git`, `trellis`, `write`, `edit`, ... */
    tool: string;
    /** Raw tool args; `bash` carries `command`, `git` carries a subcommand. */
    args: Record<string, unknown>;
    /** Working directory the tool would run in. */
    cwd: string;
}
export interface AuthorityContext {
    agentId?: string;
    sessionId?: string;
    laneId?: string;
    /** Explicit Trellis root; when omitted, derived by walking up from cwd. */
    trellisRoot?: string | null;
}
/** Direct git mutations on a Trellis-owned tree (mirrors the shell guard). */
export declare const GIT_MUTATION_PATTERN: RegExp;
/** Direct writes into `.trellis/` (the op-log / journal must only be touched by the engine). */
export declare const TRELLIS_DIR_MUTATION_PATTERN: RegExp;
/** Destructive trellis commands that require an explicit human confirm. */
export declare const TRELLIS_DESTRUCTIVE_PATTERN: RegExp;
/**
 * Walk up from `start` to the nearest directory containing a `.trellis/config.json`
 * (the documented repo marker). Returns the canonical root, or null.
 */
export declare function findTrellisRoot(start: string): string | null;
/**
 * The single decision point. Pure and synchronous — harnesses call this at
 * pre-tool time; unit tests cover the full matrix without any harness.
 */
export declare function canToolRun(inv: ToolInvocation, ctx?: AuthorityContext): ToolDecision;
//# sourceMappingURL=authority.d.ts.map