jeopi-cli 16.2.14 → 16.2.17

package/dist/types/extensibility/typebox.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Minimal `@sinclair/typebox` runtime compatibility shim.
+ *
+ * Historically the coding agent injected the real `@sinclair/typebox` (~5MB
+ * dependency) into extensions, hooks, custom tools, and custom commands so
+ * they could author parameter schemas as `Type.Object({ name: Type.String() })`.
+ *
+ * This module provides the subset those integrations depend on:
+ *
+ *   - TypeBox-style `Type.*` builders.
+ *   - Runtime validation through `schema.safeParse(input)` and `schema.__validator(input)`.
+ *   - Enumerable JSON Schema keywords so `{ ...schema }`, `JSON.stringify(schema)`,
+ *     and `toolWireSchema({ parameters: schema })` all see the same schema.
+ *
+ * Internal validator fields and methods are intentionally non-enumerable. The
+ * object should look like JSON Schema at every serialization/wire boundary and
+ * like a small validator at runtime.
+ */
+export type TSchema = ArkSchema;
+export type Static<T extends ArkSchema> = T["__infer"];
+export type TAny = ArkSchema;
+export type TUnknown = ArkSchema;
+export type TNever = ArkSchema;
+export type TNull = ArkSchema;
+export type TString = ArkSchema;
+export type TNumber = ArkSchema;
+export type TInteger = ArkSchema;
+export type TBoolean = ArkSchema;
+export type TLiteral<_V extends string | number | boolean> = ArkSchema;
+export type TArray<_E extends ArkSchema> = ArkSchema;
+export type TObject<_P extends Record<string, ArkSchema> = Record<string, ArkSchema>> = ArkSchema;
+export type TOptional<_E extends ArkSchema> = ArkSchema;
+export type TUnion<_T extends readonly ArkSchema[] = readonly ArkSchema[]> = ArkSchema;
+export type TEnum<_T extends readonly (string | number)[] = readonly (string | number)[]> = ArkSchema;
+export type TRecord<_K extends ArkSchema, _V extends ArkSchema> = ArkSchema;
+declare const VALIDATION_FAILURE: unique symbol;
+interface ValidationFailure {
+    message: string;
+    readonly [VALIDATION_FAILURE]: true;
+}
+interface SafeParseSuccess {
+    success: true;
+    data: unknown;
+}
+interface SafeParseFailure {
+    success: false;
+    error: ValidationFailure;
+}
+/**
+ * JSON-Schema-shaped object with non-enumerable runtime helpers.
+ * Validators return the validated data or a marked `{ message }` failure.
+ */
+interface ArkSchema {
+    __validator: (data: unknown) => unknown;
+    __metadata?: Record<string, unknown>;
+    __optional?: true;
+    __properties?: Record<string, ArkSchema>;
+    __additionalProperties?: boolean | ArkSchema;
+    __infer?: unknown;
+    __inner?: ArkSchema;
+    safeParse(input: unknown): SafeParseSuccess | SafeParseFailure;
+    toJSON(): Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface Meta {
+    title?: string;
+    description?: string;
+    default?: unknown;
+    examples?: unknown[];
+    [key: string]: unknown;
+}
+interface StringOpts extends Meta {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+}
+interface NumberOpts extends Meta {
+    minimum?: number;
+    maximum?: number;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
+    multipleOf?: number;
+}
+interface ArrayOpts extends Meta {
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+}
+interface ObjectOpts extends Meta {
+    /**
+     * TypeBox default: extra keys are preserved. Set `false` to reject unknowns,
+     * `true` to allow any, or a schema to validate them.
+     */
+    additionalProperties?: boolean | ArkSchema;
+}
+declare function tString(opts?: StringOpts): ArkSchema;
+declare function tNumber(opts?: NumberOpts): ArkSchema;
+declare function tInteger(opts?: NumberOpts): ArkSchema;
+declare function tBoolean(opts?: Meta): ArkSchema;
+declare function tNull(opts?: Meta): ArkSchema;
+declare function tAny(opts?: Meta): ArkSchema;
+declare function tUnknown(opts?: Meta): ArkSchema;
+declare function tNever(opts?: Meta): ArkSchema;
+declare function tLiteral<V extends string | number | boolean>(value: V, opts?: Meta): ArkSchema;
+declare function tUnion<T extends readonly ArkSchema[]>(schemas: T, opts?: Meta): ArkSchema;
+declare function tIntersect(schemas: readonly ArkSchema[], opts?: Meta): ArkSchema;
+declare function tEnum<T extends Record<string, string | number> | readonly (string | number)[]>(values: T, opts?: Meta): ArkSchema;
+declare function tArray<E extends ArkSchema>(item: E, opts?: ArrayOpts): ArkSchema;
+declare function tTuple(items: readonly ArkSchema[], opts?: Meta): ArkSchema;
+declare function tObject<P extends Record<string, ArkSchema>>(properties: P, opts?: ObjectOpts): ArkSchema;
+declare function tRecord<K extends ArkSchema, V extends ArkSchema>(key: K, value: V, opts?: Meta): ArkSchema;
+declare function tOptional<E extends ArkSchema>(schema: E, opts?: Meta): ArkSchema;
+declare function tNullable<E extends ArkSchema>(schema: E, opts?: Meta): ArkSchema;
+declare function tReadonly<E extends ArkSchema>(schema: E): ArkSchema;
+declare function tPartial<_P extends Record<string, ArkSchema>>(obj: ArkSchema): ArkSchema;
+declare function tRequired<_P extends Record<string, ArkSchema>>(obj: ArkSchema): ArkSchema;
+declare function tPick<P extends Record<string, ArkSchema>, K extends keyof P>(obj: ArkSchema, keys: readonly K[]): ArkSchema;
+declare function tOmit<P extends Record<string, ArkSchema>, K extends keyof P>(obj: ArkSchema, keys: readonly K[]): ArkSchema;
+declare function tComposite(objects: readonly ArkSchema[], opts?: Meta): ArkSchema;
+export declare const Type: {
+    readonly String: typeof tString;
+    readonly Number: typeof tNumber;
+    readonly Integer: typeof tInteger;
+    readonly Boolean: typeof tBoolean;
+    readonly Null: typeof tNull;
+    readonly Any: typeof tAny;
+    readonly Unknown: typeof tUnknown;
+    readonly Never: typeof tNever;
+    readonly Literal: typeof tLiteral;
+    readonly Union: typeof tUnion;
+    readonly Intersect: typeof tIntersect;
+    readonly Enum: typeof tEnum;
+    readonly Array: typeof tArray;
+    readonly Tuple: typeof tTuple;
+    readonly Object: typeof tObject;
+    readonly Record: typeof tRecord;
+    readonly Optional: typeof tOptional;
+    readonly Nullable: typeof tNullable;
+    readonly Readonly: typeof tReadonly;
+    readonly Partial: typeof tPartial;
+    readonly Required: typeof tRequired;
+    readonly Pick: typeof tPick;
+    readonly Omit: typeof tOmit;
+    readonly Composite: typeof tComposite;
+};
+export type TypeBuilder = typeof Type;
+/** Default namespace export so `import * as typebox from "./typebox"` still resolves the `Type` key. */
+declare const _default: {
+    Type: {
+        readonly String: typeof tString;
+        readonly Number: typeof tNumber;
+        readonly Integer: typeof tInteger;
+        readonly Boolean: typeof tBoolean;
+        readonly Null: typeof tNull;
+        readonly Any: typeof tAny;
+        readonly Unknown: typeof tUnknown;
+        readonly Never: typeof tNever;
+        readonly Literal: typeof tLiteral;
+        readonly Union: typeof tUnion;
+        readonly Intersect: typeof tIntersect;
+        readonly Enum: typeof tEnum;
+        readonly Array: typeof tArray;
+        readonly Tuple: typeof tTuple;
+        readonly Object: typeof tObject;
+        readonly Record: typeof tRecord;
+        readonly Optional: typeof tOptional;
+        readonly Nullable: typeof tNullable;
+        readonly Readonly: typeof tReadonly;
+        readonly Partial: typeof tPartial;
+        readonly Required: typeof tRequired;
+        readonly Pick: typeof tPick;
+        readonly Omit: typeof tOmit;
+        readonly Composite: typeof tComposite;
+    };
+};
+export default _default;

package/dist/types/extensibility/utils.d.ts

@@ -0,0 +1,24 @@
+import type { HookUIContext } from "./hooks/types";
+/**
+ * Resolve a file path:
+ * - Absolute paths used as-is
+ * - Paths starting with ~ expanded to home directory
+ * - Relative paths resolved from cwd
+ */
+export declare function resolvePath(filePath: string, cwd: string): string;
+/**
+ * Create a no-op UI context for headless modes.
+ */
+export declare function createNoOpUIContext(): HookUIContext;
+/**
+ * Raised by {@link withExitGuard} when a guarded callback synchronously
+ * attempts to terminate the host process. Callers catch this like any other
+ * load-time failure so the extension/hook is skipped with a logged error
+ * instead of taking the CLI down with it.
+ */
+export declare class ExtensionExitError extends Error {
+    readonly alias: string;
+    readonly code: number | string | undefined;
+    constructor(code: number | string | undefined, alias?: string);
+}
+export declare function withExitGuard<T>(fn: () => Promise<T>): Promise<T>;

package/dist/types/goals/guided-setup.d.ts

@@ -0,0 +1,18 @@
+import type { AgentSession } from "../session/agent-session";
+export interface GuidedGoalMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+export type GuidedGoalTurnResult = {
+    kind: "question";
+    question: string;
+    objective?: string;
+} | {
+    kind: "ready";
+    objective: string;
+};
+export interface GuidedGoalTurnOptions {
+    messages: readonly GuidedGoalMessage[];
+    signal?: AbortSignal;
+}
+export declare function runGuidedGoalTurn(session: AgentSession, options: GuidedGoalTurnOptions): Promise<GuidedGoalTurnResult>;

package/dist/types/goals/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./runtime";
+export * from "./state";
+export * from "./tools/goal-tool";

package/dist/types/goals/runtime.d.ts

@@ -0,0 +1,69 @@
+import type { Goal, GoalBudgetSteering, GoalModeState, GoalRuntimeEvent, GoalTokenUsage } from "./state";
+export interface GoalRuntimeHost {
+    getState(): GoalModeState | undefined;
+    setState(state: GoalModeState | undefined): void;
+    getCurrentUsage(): GoalTokenUsage;
+    emit(event: GoalRuntimeEvent): void | Promise<void>;
+    persist(mode: "goal" | "goal_paused" | "none", state?: GoalModeState): void;
+    sendHiddenMessage(message: {
+        customType: string;
+        content: string;
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+    }): Promise<void>;
+    now?(): number;
+}
+export interface GoalTurnSnapshot {
+    turnId: string;
+    baselineUsage: GoalTokenUsage;
+    activeGoalId?: string;
+}
+export interface GoalWallClockSnapshot {
+    lastAccountedAt: number;
+    activeGoalId?: string;
+}
+export interface GoalRuntimeSnapshot {
+    turnSnapshot?: GoalTurnSnapshot;
+    wallClock: GoalWallClockSnapshot;
+    budgetReportedFor?: string;
+}
+export type GoalPromptKind = "active" | "continuation" | "budget-limit";
+export declare function remainingTokens(goal: Goal | null | undefined): number | null;
+export declare function renderTrustedObjective(objective: string): string;
+export declare function goalTokenDelta(current: GoalTokenUsage, baseline: GoalTokenUsage): number;
+export declare function renderGoalPrompt(kind: GoalPromptKind, goal: Goal): string;
+export declare function completionBudgetReport(goal: Goal): string | null;
+export declare class GoalRuntime {
+    #private;
+    constructor(host: GoalRuntimeHost);
+    get snapshot(): GoalRuntimeSnapshot;
+    clearAccounting(): void;
+    onTurnStart(turnId: string, baselineUsage: GoalTokenUsage): void;
+    onToolCompleted(toolName: string): Promise<void>;
+    onGoalToolCompleted(): Promise<void>;
+    onAgentEnd(options?: {
+        turnCompleted?: boolean;
+        currentUsage?: GoalTokenUsage;
+    }): Promise<void>;
+    onTaskAborted(options?: {
+        reason?: "interrupted" | "internal";
+    }): Promise<void>;
+    onThreadResumed(options?: {
+        preserveActiveGoal?: boolean;
+    }): Promise<GoalModeState | undefined>;
+    onBudgetMutated(newBudget: number | undefined): Promise<GoalModeState | undefined>;
+    flushUsage(steering: GoalBudgetSteering, currentUsage?: GoalTokenUsage): Promise<void>;
+    createGoal(input: {
+        objective: string;
+        tokenBudget?: number;
+    }): Promise<GoalModeState>;
+    replaceGoal(input: {
+        objective: string;
+        tokenBudget?: number;
+    }): Promise<GoalModeState>;
+    resumeGoal(): Promise<GoalModeState>;
+    pauseGoal(): Promise<GoalModeState | undefined>;
+    dropGoal(): Promise<Goal | undefined>;
+    completeGoalFromTool(): Promise<Goal>;
+    buildActivePrompt(): string | undefined;
+    buildContinuationPrompt(): string | undefined;
+}

package/dist/types/goals/state.d.ts

@@ -0,0 +1,35 @@
+import type { UsageStatistics } from "../session/session-entries";
+export type GoalStatus = "active" | "paused" | "budget-limited" | "complete" | "dropped";
+export interface Goal {
+    id: string;
+    objective: string;
+    status: GoalStatus;
+    tokenBudget?: number;
+    tokensUsed: number;
+    timeUsedSeconds: number;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface GoalModeState {
+    enabled: boolean;
+    mode: "active" | "exiting";
+    reason?: "completed";
+    goal: Goal;
+}
+export interface GoalToolDetails {
+    op: "create" | "get" | "complete" | "resume" | "drop";
+    goal?: Goal | null;
+    remainingTokens?: number | null;
+    completionBudgetReport?: string | null;
+}
+export type GoalRuntimeEvent = {
+    type: "goal_updated";
+    goal: Goal | null;
+    state?: GoalModeState;
+} | {
+    type: "goal_continuation_requested";
+    prompt: string;
+};
+export type GoalTokenUsage = Pick<UsageStatistics, "input" | "output" | "cacheRead" | "cacheWrite">;
+export type GoalBudgetSteering = "allowed" | "suppressed";
+export type GoalTerminalMetricEmission = "emit" | "suppress";

package/dist/types/goals/tools/goal-tool.d.ts

@@ -0,0 +1,53 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "jeopi-agent-core";
+import type { Component } from "jeopi-tui";
+import type { RenderResultOptions } from "../../extensibility/custom-tools/types";
+import type { Theme } from "../../modes/theme/theme";
+import type { ToolSession } from "../../tools";
+import type { Goal, GoalToolDetails } from "../state";
+declare const goalSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    op: "complete" | "create" | "drop" | "get" | "resume";
+    objective?: string | undefined;
+    token_budget?: number | undefined;
+}, {}>;
+export type GoalToolInput = typeof goalSchema.infer;
+export interface GoalToolResponse {
+    goal: Goal | null;
+    remainingTokens: number | null;
+    completionBudgetReport: string | null;
+}
+export declare function buildGoalToolResponse(goal: Goal | null | undefined, options?: {
+    includeCompletionReport?: boolean;
+}): GoalToolResponse;
+export declare class GoalTool implements AgentTool<typeof goalSchema, GoalToolDetails> {
+    #private;
+    readonly name = "goal";
+    readonly label = "Goal";
+    readonly description: string;
+    readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
+        op: "complete" | "create" | "drop" | "get" | "resume";
+        objective?: string | undefined;
+        token_budget?: number | undefined;
+    }, {}>;
+    readonly strict = true;
+    readonly intent: "omit";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: GoalToolInput, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<GoalToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<GoalToolDetails>>;
+}
+interface GoalRenderArgs {
+    op?: GoalToolInput["op"];
+    objective?: string;
+    token_budget?: number;
+}
+export declare const goalToolRenderer: {
+    renderCall(args: GoalRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: GoalToolDetails;
+        isError?: boolean;
+    }, _options: RenderResultOptions, uiTheme: Theme, args?: GoalRenderArgs): Component;
+    mergeCallAndResult: boolean;
+};
+export {};

package/dist/types/hindsight/backend.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Hindsight memory backend.
+ *
+ * Wires the per-session lifecycle (recall on first turn, retain every Nth
+ * agent_end, etc.) on top of the AgentSession event stream. Hindsight runtime
+ * state is owned by the AgentSession so lifetime follows the actual domain
+ * owner instead of a parallel session-id registry.
+ */
+import type { MemoryBackend } from "../memory-backend/types";
+import type { AgentSession } from "../session/agent-session";
+/** Reload the active session's mental-model cache and prompt. */
+export declare function reloadMentalModelsForSession(session: AgentSession): Promise<boolean>;
+export declare const hindsightBackend: MemoryBackend;

package/dist/types/hindsight/bank.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Bank ID derivation, project-tag scoping, and first-use bank setup.
+ *
+ * Three scoping modes (`HindsightConfig.scoping`):
+ *   - `global`              — single shared bank, no per-project filter.
+ *   - `per-project`         — one bank per cwd basename, hard isolation.
+ *   - `per-project-tagged`  — single shared bank, retains carry a `project:<name>`
+ *                              tag and recall filters on it but still surfaces
+ *                              untagged ("global") memories alongside.
+ *
+ * The base bank id is `bankIdPrefix-bankId` (default `omp`, kept for storage
+ * compatibility with pre-rename installs). Per-project mode
+ * appends `-<project>`; tagged mode leaves the bank untouched and uses tags.
+ *
+ * Bank existence is idempotent at module level — a banksSet keeps track of
+ * banks we've already PUT so each session boundary doesn't fire a fresh
+ * `createBank` call. The PUT is idempotent server-side, so re-firing on a hot
+ * path would only burn round-trips. Failures are swallowed: missing the
+ * mission patch is an optimisation, but the bank ITSELF must exist before
+ * mental-model bootstrap or the first retain, otherwise the very first POST
+ * lands against a missing bank.
+ */
+import type { HindsightApi } from "./client";
+import type { HindsightConfig } from "./config";
+export type RecallTagsMatch = "any" | "all" | "any_strict" | "all_strict";
+/**
+ * Resolved bank target for a session: which bank to talk to, plus optional
+ * tags to attach to retains and to filter recalls by.
+ */
+export interface BankScope {
+    bankId: string;
+    /** Tags applied to every retain. Undefined when scoping does not use tags. */
+    retainTags?: string[];
+    /** Tags filter for recall/reflect. Undefined when scoping does not use tags. */
+    recallTags?: string[];
+    /** Match mode for `recallTags`. Defaults to `any` so untagged ("global") memories surface too. */
+    recallTagsMatch?: RecallTagsMatch;
+}
+/**
+ * Resolve the active bank target plus optional tag scoping.
+ *
+ * Always returns a non-empty `bankId`. Tag fields are populated only for
+ * `per-project-tagged`.
+ */
+export declare function computeBankScope(config: HindsightConfig, directory: string): BankScope;
+/**
+ * Backwards-compatible thin wrapper: just return the bank id portion of the
+ * scope. New code should prefer `computeBankScope` directly so it can also
+ * apply the tag fields.
+ */
+export declare function deriveBankId(config: HindsightConfig, directory: string): string;
+/**
+ * Ensure a bank exists, and patch its reflect/retain mission on first use.
+ *
+ * Idempotent: skips the PUT when the bank id is already in the supplied set.
+ * The mission body is optional — when `bankMission` is blank we still PUT to
+ * make sure the bank itself is created, so mental-model bootstrap and the
+ * first retain don't land against a non-existent bank.
+ *
+ * The set is capped; on overflow we drop the oldest half so it cannot grow
+ * unboundedly across long-lived processes.
+ */
+export declare function ensureBankExists(client: HindsightApi, bankId: string, config: HindsightConfig, banksSet: Set<string>): Promise<void>;