dsh-pstack 0.2.0-beta.1 → 0.2.0

package/dist/history.d.mts

@@ -1,429 +0,0 @@
-import { _ as ToolRunContext, c as SessionEvent, d as SessionQueryHost, g as ToolDefinition, l as SessionHeader, m as SubagentCatalogHost, o as JsonSchemaNode, p as SubagentCatalogEntry, v as ToolsHost } from "./host-contract-o47JH_r8.mjs";
-//#region src/history.d.ts
-/** Cordis row name, used by Loader diagnostics. */
-export declare const name = "pstack-history";
-/**
- * The row needs the tool registry and the subagent catalog; `sessionQuery` does not.
- *
- * Declaring `sessionQuery` here made it a *hard* dependency, and Cordis's semantics
- * are that a missing injected service keeps the fiber inactive and a removed one
- * disposes it. So in a profile without `sessionQuery` the tool never registered at
- * all, and disposing the service unregistered it — the model saw "no such tool"
- * instead of the `unavailable` result this module is built to return, and the
- * `MISSING_SESSION_QUERY` branch was reachable only from tests with a hand-built
- * runtime.
- *
- * Reading it through `ctx.get("sessionQuery")` instead — rc.3's optional-service
- * form, which returns `undefined` rather than throwing — keeps the tool registered
- * and lets the call answer honestly.
- */
-export declare const inject: string[];
-/** Model-facing tool name. */
-export declare const TOOL_NAME = "pstack_history";
-/** Events returned when the call omits `limit`. */
-export declare const DEFAULT_LIMIT = 50;
-/** Largest `limit` a call may request. A larger value is rejected, not clamped. */
-export declare const MAX_LIMIT = 200;
-/**
- * Soft ceiling for one page's serialized events.
- *
- * The slicer always returns at least one event so a caller can make progress
- * through one oversized event, and reports `truncatedByBytes` when the ceiling
- * stopped the page before `limit` did.
- */
-export declare const MAX_PAGE_BYTES: number;
-/** Scopes the tool understands. Descendant traversal is not implemented. */
-export declare const HISTORY_SCOPES: readonly ["current", "children"];
-export type HistoryScope = (typeof HISTORY_SCOPES)[number];
-/**
- * Why a read could not produce events, by the layer that failed.
- *
- * `input` is the caller's own request — a combination of arguments this tool refuses,
- * such as a continuation page that omits `throughSeq`. It is separate from the
- * service layers because the fix belongs to the caller, not to the Host.
- */
-export type HistoryFailureLayer = "authorization" | "input" | "session-query" | "persistence" | "backend";
-export interface HistoryArgs {
-  readonly scope: HistoryScope;
-  readonly sessionId?: string;
-  readonly fromSeq: number;
-  /** Inclusive upper bound pinned by the caller, when one was supplied. */
-  readonly throughSeq?: number;
-  readonly limit: number;
-}
-export interface HistorySessionView {
-  readonly id: string;
-  readonly version: number;
-  readonly createdAt: number;
-  readonly cwd: string | null;
-  readonly parentSession: string | null;
-  readonly origin: "subagent" | null;
-  readonly delegationDepth: number | null;
-  readonly agentPreset: string | null;
-  readonly isSeeded: boolean;
-}
-export interface HistoryEventView {
-  readonly seq: number;
-  readonly time: number;
-  readonly type: string;
-  readonly data: unknown;
-  readonly surfaceOp: SessionEvent["surfaceOp"] | null;
-  readonly sourceEventSeqs: readonly number[] | null;
-}
-export interface HistoryPageView {
-  readonly fromSeq: number;
-  readonly limit: number;
-  /** Inclusive snapshot boundary every returned seq stays inside. */
-  readonly throughSeq: number;
-  /**
-   * True when `throughSeq` came from the caller rather than from this call's
-   * snapshot.
-   *
-   * A continuation page must pin the boundary from the first page. When this is
-   * false the boundary moved with this call, and comparing two pages of one audit is
-   * not sound.
-   */
-  readonly pinnedThroughSeq: boolean;
-  readonly returned: number;
-  readonly firstSeq: number | null;
-  readonly lastSeq: number | null;
-  readonly nextFromSeq: number | null;
-  readonly hasMore: boolean;
-  readonly truncatedByBytes: boolean;
-  /** Sequence numbers of this call's own `tool/call` events left out of the page. */
-  readonly excludedOwnCallSeqs: readonly number[];
-}
-export interface HistoryProvenanceView {
-  /**
-   * `source-log` means every returned event is the first-party log of that
-   * session. `undeterminable` means the host cannot attribute the events.
-   */
-  readonly determination: "source-log" | "undeterminable";
-  /**
-   * Always `null` in rc.3: no public method reports the persisted boundary of an
-   * observed log, for either source.
-   */
-  readonly persistedThroughSeq: number | null;
-  readonly note: string;
-}
-export interface HistoryChildView {
-  readonly sessionId: string;
-  readonly label: string;
-  readonly createdAt: number;
-}
-export interface HistoryRelationsView {
-  /** Whether the child catalog could be read at all. */
-  readonly catalogAvailable: boolean;
-  /** The caller's reviewable direct children. Ids of other modes are never listed. */
-  readonly directChildren: readonly HistoryChildView[];
-  /** Counts, never ids, for direct children this tool will not read. */
-  readonly excluded: {
-    readonly external: number;
-    readonly oneShot: number;
-    readonly unknown: number;
-  };
-  /** Present when the read targeted a child. */
-  readonly parentSessionId: string | null;
-  /** Descendant traversal is not implemented, so this is always `false`. */
-  readonly descendantsSupported: false;
-}
-export interface HistoryAuditView {
-  /** False when the events cannot be attributed to the first-party log. */
-  readonly complete: boolean;
-  /** `full` only when the page starts at seq 0 and has no further page. */
-  readonly coverage: "full" | "partial" | "none";
-  readonly blockers: readonly string[];
-}
-export type HistoryResult = {
-  readonly kind: "events";
-  readonly callerSessionId: string;
-  readonly requestedSessionId: string;
-  readonly scope: HistoryScope;
-  /** The lease that produced this page, after the fact. */
-  readonly snapshotSource: "live" | "prepared";
-  readonly revision: string | null;
-  readonly session: HistorySessionView;
-  readonly page: HistoryPageView;
-  readonly provenance: HistoryProvenanceView;
-  readonly relations: HistoryRelationsView;
-  readonly audit: HistoryAuditView;
-  readonly events: readonly HistoryEventView[];
-  readonly notes: readonly string[];
-} | {
-  readonly kind: "children";
-  readonly callerSessionId: string;
-  readonly requestedSessionId: null;
-  readonly scope: "children";
-  readonly relations: HistoryRelationsView;
-  readonly notes: readonly string[];
-} | {
-  readonly kind: "denied";
-  readonly callerSessionId: string | null;
-  readonly requestedSessionId: string | null;
-  readonly scope: HistoryScope;
-  readonly layer: "authorization";
-  readonly code: string;
-  /** Actionable sentence naming the failed check, never backend text. */
-  readonly message: string;
-  readonly notes: readonly string[];
-} | {
-  readonly kind: "unavailable";
-  readonly callerSessionId: string | null;
-  readonly requestedSessionId: string | null;
-  readonly scope: HistoryScope;
-  readonly layer: Exclude<HistoryFailureLayer, "authorization">;
-  readonly code: string;
-  readonly message: string;
-  readonly notes: readonly string[];
-};
-/** Thrown for a malformed call. The registry surfaces it as a tool error. */
-export declare class HistoryInputError extends Error {
-  readonly code: string;
-  constructor(message: string, code?: string);
-}
-/**
- * Validate one call.
- *
- * `limit` above `MAX_LIMIT` is rejected rather than clamped: a caller that asks
- * for 10 000 events is trying to read a whole log in one shot, and a silent
- * clamp would look like the tool agreed.
- */
-export declare function parseHistoryArgs(raw: unknown): HistoryArgs;
-export type TargetAuthorization = {
-  readonly kind: "self";
-} | {
-  readonly kind: "child";
-  readonly label: string;
-};
-export type AuthorizationRejection = "missing-agent" | "not-a-direct-child" | "child-not-reviewable";
-/**
- * First half of the child check: the catalog row, before any backend read.
- *
- * A target equal to the caller is always self. Anything else must appear in the
- * caller's own direct-child catalog with `mode: "continuable"`.
- */
-export declare function authorizeTarget(callerId: string | null, targetId: string, entries: readonly SubagentCatalogEntry[]): TargetAuthorization | AuthorizationRejection;
-export type ObservedRejection = "target-changed" | "lineage-mismatch" | "workspace-unknown" | "cross-workspace";
-export interface ObservedAuthorizationInput {
-  readonly callerId: string;
-  readonly targetId: string;
-  readonly target: TargetAuthorization;
-  readonly observedHeader: SessionHeader;
-  /** The caller's own `cwd`, read from the corpus before the target. */
-  readonly callerCwd: string | undefined;
-}
-/**
- * How a child's recorded directory relates to the caller's current one.
- *
- * A child's `cwd` is fixed when the child is created (`prepareContinuable` in
- * `dsh-subagent` resolves the directory and writes it into the header), while
- * `create_worktree` and `workingDirectory.set` change only the *current*
- * directory of a session. So a child legitimately started in a worktree or a
- * subdirectory of the caller's project has a different `cwd` from the caller even
- * though it is working on the same project.
- *
- * Both sides are normalised with `resolve` first, which absorbs separator
- * differences, trailing slashes, and `..` segments on every platform:
- *
- * - `same`    — identical after normalisation.
- * - `nested`  — the child sits inside the caller's directory. Worktree pools and
- *               `repo/sub` land here: working isolation, not a foreign project.
- * - `foreign` — anything else, which stays `cross-workspace`.
- */
-export declare function workspaceRelation(callerCwd: string, childCwd: string): "same" | "nested" | "foreign";
-/**
- * Second half of authorization, run against the header actually returned.
- *
- * This repeats the identity and workspace check on the data that will be
- * rendered, so a header that disagrees with the requested target, the claimed
- * parent, or the caller's workspace is rejected before any event leaves the
- * tool. `traceSession` is deliberately not consulted: lineage is a naming
- * source, and reading it would add a third observation without granting
- * anything the catalog row and `parentSession` do not already establish.
- */
-export declare function authorizeObserved(input: ObservedAuthorizationInput): ObservedRejection | null;
-/** Render one authorization rejection for the caller. */
-export declare function describeAuthorizationFailure(rejection: AuthorizationRejection): {
-  readonly code: string;
-  readonly message: string;
-};
-/** Render one observed-header rejection for the caller. */
-export declare function describeObservedFailure(rejection: ObservedRejection): {
-  readonly code: string;
-  readonly message: string;
-};
-/**
- * Split a direct-child catalog into the rows this tool will read and counts of
- * the ones it will not.
- *
- * Only continuable ids leave this function. External, one-shot, and unknown
- * rows are counted so a caller can tell "no children" from "children I may not
- * read" without learning ids it was not granted.
- */
-export declare function describeRelations(callerId: string | null, entries: readonly SubagentCatalogEntry[] | null): HistoryRelationsView;
-export interface SliceInput {
-  readonly events: readonly SessionEvent[];
-  readonly fromSeq: number;
-  readonly limit: number;
-  /** Inclusive upper bound taken from the observation, never re-read later. */
-  readonly throughSeq: number;
-  /** `callId`s of this call's own `tool/call` events. */
-  readonly ownCallIds?: readonly string[];
-  readonly maxBytes?: number;
-}
-export interface SliceResult {
-  readonly events: readonly SessionEvent[];
-  readonly nextFromSeq: number | null;
-  readonly hasMore: boolean;
-  readonly truncatedByBytes: boolean;
-  readonly excludedOwnCallSeqs: readonly number[];
-}
-/**
- * Cut one page out of one fixed snapshot.
- *
- * Rules, in order: keep events inside `[fromSeq, throughSeq]`; drop this call's
- * own `tool/call` events so the audit basis cannot contain the act of auditing;
- * take `limit` events; stop early only once at least one event is present and the
- * byte ceiling would be crossed. `nextFromSeq` is the first unreturned seq, so a
- * gap left by an excluded event can never be read as "no more events".
- */
-export declare function sliceEvents(input: SliceInput): SliceResult;
-/** The fields of one observation the DTO keeps after the lease is released. */
-export interface ObservationFacts {
-  readonly header: SessionHeader;
-  readonly source: "live" | "prepared";
-  readonly revision?: string;
-  readonly events: readonly SessionEvent[];
-  readonly cursor: number;
-  readonly inheritedEventCount: number;
-}
-export interface AssembleInput {
-  readonly args: HistoryArgs;
-  readonly callerSessionId: string;
-  readonly targetId: string;
-  readonly target: TargetAuthorization;
-  readonly facts: ObservationFacts;
-  readonly relations: HistoryRelationsView;
-  readonly ownCallIds: readonly string[];
-}
-/**
- * Build one events page.
- *
- * The caller's `throughSeq` pins the window when supplied, so page two of the
- * same audit cannot absorb an append that landed between the calls. A requested
- * bound beyond the snapshot is clamped down to the snapshot, never extended.
- *
- * A *continuation* page has to pass that boundary back, and this function does not
- * fake it: `readHistory` rejects a `fromSeq > 0` call that omits `throughSeq` before
- * reaching here, because each call re-observes the session and `facts.cursor` would
- * otherwise be the *new* boundary. Silently moving it lets the audit absorb events
- * that did not exist when the first page was read, which is exactly what the design
- * forbids.
- */
-export declare function assembleEventsResult(input: AssembleInput): Extract<HistoryResult, {
-  kind: "events";
-}>;
-/**
- * State what rc.3 can and cannot attribute.
- *
- * A live observation is a fixed snapshot of the in-memory log, so every event in
- * it is first-party. A prepared observation is read from persistence, closed,
- * and then extended in memory with synthetic interrupted-turn closers; rc.3
- * exposes neither their marker nor the persisted boundary, and the closers reuse
- * ordinary event types and reasons. Attribution is therefore impossible for a
- * cold read, and this result says so instead of presenting repair events as
- * original evidence.
- */
-export declare function describeProvenance(facts: Pick<ObservationFacts, "source">): HistoryProvenanceView;
-interface SafeFailure {
-  readonly layer: Exclude<HistoryFailureLayer, "authorization">;
-  readonly code: string;
-  readonly message: string;
-}
-/**
- * Translate one thrown backend error into a safe failure.
- *
- * The original message is never echoed, and no `cause` is attached: both can
- * contain storage paths and ids outside the caller's grant.
- */
-export declare function classifyBackendFailure(error: unknown): SafeFailure;
-/** Build the `unavailable` DTO for a backend or missing-service failure. */
-export declare function unavailableResult(input: {
-  readonly callerSessionId: string | null;
-  readonly requestedSessionId: string | null;
-  readonly scope: HistoryScope;
-  readonly failure: SafeFailure;
-  readonly notes?: readonly string[];
-}): Extract<HistoryResult, {
-  kind: "unavailable";
-}>;
-/** The failure used when the row has no `sessionQuery` service at all. */
-export declare const MISSING_SESSION_QUERY: SafeFailure;
-/** Build the `denied` DTO for an authorization rejection. */
-export declare function deniedResult(input: {
-  readonly callerSessionId: string | null;
-  readonly requestedSessionId: string | null;
-  readonly scope: HistoryScope;
-  readonly code: string;
-  readonly message: string;
-}): Extract<HistoryResult, {
-  kind: "denied";
-}>;
-/** Build the catalog-only DTO for `scope: "children"` without a target. */
-export declare function childrenResult(input: {
-  readonly callerSessionId: string;
-  readonly relations: HistoryRelationsView;
-}): Extract<HistoryResult, {
-  kind: "children";
-}>;
-/** Render one result as text. Every field is present so an auditor sees the basis. */
-export declare function renderHistoryResult(result: HistoryResult): string;
-/** The declared shape of one result. Kept next to the assembler it describes. */
-export declare const OUTPUT_SCHEMA: JsonSchemaNode;
-export declare const TOOL_DESCRIPTION: string;
-/**
- * The service slices this row reads.
- *
- * `sessionQuery` is deliberately absent: it is not injected, so a typed field for it
- * would tell callers they may pass it while `apply` never reads it. It is fetched by
- * name on each call instead.
- */
-export interface PstackHistoryHost {
-  readonly tools: ToolsHost;
-  readonly subagents: SubagentCatalogHost;
-}
-/** What one execute reads. Injected so tests can drive each layer apart. */
-export interface HistoryRuntime {
-  readonly subagents: SubagentCatalogHost;
-  /** Read per call so a service that arrives or leaves is observed. */
-  getSessionQuery(): SessionQueryHost | undefined;
-}
-/**
- * Read one authorized page.
- *
- * Order matters and is deliberate: the caller is resolved from the execution
- * context, the target is authorized against the catalog, the log is observed,
- * the returned header is authorized again, and only then is a DTO built. The
- * lease is released in `finally` on every path, including a throw from the
- * slicer or the renderer.
- */
-export declare function readHistory(args: HistoryArgs, exec: ToolRunContext, runtime: HistoryRuntime): Promise<HistoryResult>;
-/** Build the tool for one row. */
-export declare function createHistoryTool(runtime: HistoryRuntime): ToolDefinition;
-/**
- * Register `pstack_history` for this row.
- *
- * `sessionQuery` is read through `ctx.get(...)` on every call rather than injected, so
- * a profile without it still gets the tool and a call returns `unavailable` instead of
- * the tool vanishing. That also makes a later `dispose()` of the service observable:
- * the next call reports the missing layer rather than an empty log.
- *
- * @param ctx - context providing the tool registry, the child catalog, and optionally
- *   the query service.
- */
-export declare function apply(ctx: PstackHistoryHost & {
-  get?: (name: string) => SessionQueryHost | undefined;
-}): void;
-//#endregion
-export {};
-//# sourceMappingURL=history.d.mts.map