@yadsh/dsh-qa-surface 0.9.0 → 0.11.0

package/lib/types/qa-tools/docs-tools.d.ts

@@ -0,0 +1,160 @@
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+/**
+ * `docs_search` and `docs_read` — the documentation surface of the QA catalog.
+ *
+ * A QA chat answers questions from the stand's documentation, and until now the
+ * model had no tool that said where that documentation is: the path in a
+ * reviewer's remark (`docs/platform/3.8/…`) was something the model had to
+ * guess its way to with a glob sweep, and a miss read as "the document does
+ * not exist" rather than "wrong tree". These two tools make the tree a
+ * first-class surface. Both are read-only, both are fenced to the
+ * documentation directory inside the calling chat's workspace
+ * (`<session cwd>/docs`, the directory the stand publishes its documentation
+ * into), and both name the documentation as what they search, so the tool
+ * description itself answers "where do I look for documentation?".
+ *
+ * The tree is read as a shallow layout convention, not a schema: hits carry
+ * the `version` and `module` parsed out of the path (`docs/<module>/<version>/…`)
+ * so the model can stay inside one edition of one module, and the same two
+ * names are accepted as filters. A path the convention does not describe is
+ * still searched and still read — it simply carries no identity.
+ *
+ * Nothing here is destructive and building it registers nothing: like the rest
+ * of the catalog these are side-effect-free definitions, and the workspace root
+ * is read from `exec.agent` at call time.
+ */
+/** The documentation directory inside a chat workspace. */
+export declare const QA_DOCS_DIRECTORY = "docs";
+/** Search defaults and budgets, all fixed: a chat cannot raise them. */
+export declare const QA_DOCS_SEARCH_DEFAULT_LIMIT = 8;
+export declare const QA_DOCS_SEARCH_MAX_LIMIT = 40;
+export declare const QA_DOCS_SEARCH_BYTE_BUDGET = 4000;
+export declare const QA_DOCS_READ_DEFAULT_LINES = 120;
+export declare const QA_DOCS_READ_MAX_LINES = 400;
+/** Why a documentation tool refused a call. */
+export type QaDocsRefusal = "workspace-unavailable" | "docs-unavailable" | "invalid-request" | "outside-docs" | "symlink-escape" | "not-found" | "not-a-file" | "not-text";
+/**
+ * A typed refusal of one documentation call.
+ *
+ * The message is what the model reads. It names the reason in words and never
+ * echoes an absolute host path, so a refusal cannot leak the deployment's
+ * layout into the conversation.
+ */
+export declare class QaDocsError extends Error {
+    readonly code: QaDocsRefusal;
+    constructor(code: QaDocsRefusal, message: string, options?: ErrorOptions);
+}
+/** The slice of the execution record these tool bodies read. */
+interface QaDocsExecution {
+    readonly agent?: {
+        readonly session: {
+            readonly header: {
+                readonly cwd?: string;
+            };
+        };
+    };
+}
+/** The resolved documentation root of one call. */
+export interface QaDocsRoot {
+    /** Canonical workspace root of the calling chat. */
+    readonly workspace: string;
+    /** Canonical `<workspace>/docs`. */
+    readonly docs: string;
+}
+/**
+ * Module/version identity parsed out of a documentation path.
+ *
+ * Both are optional and, when a path does not carry one, genuinely absent: the
+ * catalog's output schema is read with `exactOptionalPropertyTypes`, so an
+ * identity is spread into a report rather than written as `undefined`.
+ */
+export interface QaDocsIdentity {
+    readonly version?: string;
+    readonly module?: string;
+}
+/** One documentation match. */
+export interface QaDocsHit extends QaDocsIdentity {
+    /** Workspace-relative path, starting at `docs/`, with forward slashes. */
+    readonly path: string;
+    /** 1-based line number inside the file. */
+    readonly line: number;
+    /** The matched line, trimmed and bounded. */
+    readonly text: string;
+}
+/** The outcome of one documentation search. */
+export interface QaDocsSearchResult extends QaDocsIdentity {
+    readonly query: string;
+    /** The directory documentation is read from, relative to the workspace. */
+    readonly root: string;
+    readonly hits: QaDocsHit[];
+    readonly truncated: boolean;
+    readonly filesScanned: number;
+    readonly skipped: number;
+}
+/** The outcome of one documentation read. */
+export interface QaDocsReadResult extends QaDocsIdentity {
+    readonly path: string;
+    readonly from: number;
+    readonly to: number;
+    readonly totalLines: number;
+    readonly truncated: boolean;
+    readonly text: string;
+}
+/**
+ * Identity of one documentation path, read relative to the documentation root.
+ *
+ * The documented layout is `docs/<module>/<version>/…`: the version is the
+ * first directory segment that parses as one (`3.8`, `v2`, `2024.1`), and the
+ * module is the directory segment immediately before it. A path with no
+ * version segment keeps its first directory segment as the module; a file
+ * directly in `docs/` carries neither, and is still searched and read.
+ */
+export declare function docsIdentityOf(pathFromDocsRoot: string): QaDocsIdentity;
+/**
+ * The canonical documentation root of one call.
+ *
+ * The root is a real directory inside the canonical workspace: a `docs` entry
+ * that is a link or a file is refused rather than followed, because the fence
+ * is the point of the tool and a link is how a fence is left.
+ */
+export declare function docsRootOf(exec: QaDocsExecution): Promise<QaDocsRoot>;
+export interface QaDocsSearchRequest {
+    readonly query: string;
+    readonly version?: string | undefined;
+    readonly module?: string | undefined;
+    readonly path?: string | undefined;
+    readonly limit?: number | undefined;
+}
+/**
+ * Search the documentation tree of one chat workspace.
+ *
+ * Matching is a case-insensitive substring test, line by line: a hit is a
+ * line, not a file, so the caller can cite it. The result is bounded twice —
+ * by `limit` hits and by the byte budget of the rendered report — and reports
+ * which bound cut it short instead of silently dropping matches.
+ * @throws QaDocsError when the tree is missing, the scope path is wrong, or the query is empty.
+ */
+export declare function searchDocumentation(root: QaDocsRoot, request: QaDocsSearchRequest): Promise<QaDocsSearchResult>;
+export interface QaDocsReadRequest {
+    readonly path: string;
+    readonly from?: number | undefined;
+    readonly lines?: number | undefined;
+}
+/**
+ * Read one window of one documentation file of a chat workspace.
+ * @throws QaDocsError when the path is outside the tree, missing, a directory, or not text.
+ */
+export declare function readDocumentation(root: QaDocsRoot, request: QaDocsReadRequest): Promise<QaDocsReadResult>;
+/**
+ * `docs_search` — the catalog's documentation search.
+ *
+ * The description is part of the tool's job: it states that documentation is
+ * read here, from `docs/`, and that memory is not a documentation source. The
+ * version/module facets exist so a model that has been told "3.8" stops
+ * sweeping the whole tree.
+ */
+export declare function createDocsSearchTool(): ToolDefinition;
+/** `docs_read` — open one documentation file at a bounded window of lines. */
+export declare function createDocsReadTool(): ToolDefinition;
+export {};
+//# sourceMappingURL=docs-tools.d.ts.map

package/lib/types/qa-tools/file-delete-gate.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { QaSessionOwnership } from "../session-ownership.js";
+/** The one QA tool whose every call is parked for the operator. */
+export declare const QA_FILE_DELETE_TOOL = "file_delete";
+/** Why the gate answers `ask` before the chain can decide alone. */
+export declare const QA_FILE_DELETE_ASK_REASON = "deleting a workspace file requires operator confirmation";
+/**
+ * The inner half of `file_delete`'s safety: the decision that composes the
+ * approval flow around one destructive tool.
+ *
+ * Installed WITHOUT `prepend`, deliberately. The approval gate sits outside
+ * every other `tools/pre-execute` listener and resolves the decision the rest
+ * of the chain produced — an `ask` from an inner gate is what it parks for
+ * the operator. This listener is that inner gate: for a `file_delete` call
+ * from an attested QA session it answers `ask` on its own, without asking
+ * the chain, so the interactive approval card appears for every deletion,
+ * whatever the deployment's other policies would have said. The operator's
+ * answer becomes the decision, and on a deployment with
+ * `interaction.approvals: blocked` the approval gate keeps its fail-closed
+ * behavior and refuses the call — nothing is ever deleted without a person.
+ *
+ * Any other tool, and any caller this deployment did not attest, is handed
+ * back to the chain untouched.
+ */
+export declare class QaFileDeleteGate {
+    private readonly ctx;
+    private readonly ownership;
+    private readonly disposers;
+    constructor(ctx: Context, ownership: QaSessionOwnership);
+    /** Sit inside the approval gate; registration order is the composition. */
+    install(): void;
+    /** Detach the listener. Wired as an effect, like every other gate. */
+    dispose(): void;
+    private handle;
+    /**
+     * Whether this deployment attested the chat the call belongs to, delegated
+     * children included. The same ownership service the approval gate reads,
+     * so one chat is parked under exactly one surface.
+     */
+    private attested;
+}
+//# sourceMappingURL=file-delete-gate.d.ts.map

package/lib/types/qa-tools/file-delete.d.ts

@@ -0,0 +1,32 @@
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+/**
+ * `file_delete` — the QA catalog's one destructive capability.
+ *
+ * The QA surface serves untrusted-audience chats pinned to a read-only or
+ * workspace-write sandbox, and until now no chat could remove a file it had
+ * created. This tool deletes exactly one regular file strictly inside the
+ * calling agent's workspace root (the session cwd) and refuses everything
+ * else with a reason the model can act on: directories, missing paths, paths
+ * spelled outside the root, and paths that leave it through a symbolic link.
+ * Every call is additionally answered `ask` by the always-ask gate, so the
+ * interactive approval card parks it for the operator before this body ever
+ * runs — the fence here is the second of two boundaries, not the only one.
+ *
+ * The workspace root is read from `exec.agent` at call time, so building the
+ * tool (and the catalog that carries it) stays side-effect free.
+ */
+/** Why `file_delete` refused a call. */
+export type QaFileDeleteRefusal = "workspace-unavailable" | "outside-workspace" | "symlink-escape" | "not-found" | "not-a-file";
+/**
+ * A typed refusal of one `file_delete` call.
+ *
+ * The message is what the model reads; it names the reason in words and
+ * deliberately never echoes the requested absolute host path, so a refusal
+ * cannot leak the deployment's layout into the conversation.
+ */
+export declare class QaFileDeleteError extends Error {
+    readonly code: QaFileDeleteRefusal;
+    constructor(code: QaFileDeleteRefusal, message: string, options?: ErrorOptions);
+}
+export declare function createFileDeleteTool(): ToolDefinition;
+//# sourceMappingURL=file-delete.d.ts.map

package/lib/types/secure-session.d.ts

@@ -14,6 +14,13 @@ export interface QaAccountsGate {
         readonly id: string;
     } | undefined;
     userWorkspace(userId: string, registeredWorkspacePath: string): string;
+    /**
+     * The account an ownership record names, for callers that authenticated by
+     * another credential (the integration API's service token). Absent records
+     * and a changed owner both resolve to undefined. Only read by that path: the
+     * token-shaped entry above remains the browser's only door.
+     */
+    ownerIdOf(sessionId: string): string | undefined;
 }
 /**
  * Host-side QA policy admission boundary — the only browser-callable operation
@@ -48,6 +55,11 @@ export declare class QaPolicyAdmission {
      */
     private readonly attested;
     private readonly workspaceAccess;
+    /**
+     * Removers of the document input roots granted per session, so a grant lives
+     * exactly as long as the workspace access that justified it.
+     */
+    private readonly documentInputRoots;
     /**
      * Every name reachable anywhere in one QA conversation, keyed by session id.
      *
@@ -67,7 +79,9 @@ export declare class QaPolicyAdmission {
      */
     dynamicToolNames?: (agent: Agent) => readonly string[], 
     /** Resolve and freeze the session's subrole policy after its agent exists. */
-    capabilityPolicy?: ((token: string, sessionId: string, agent: Agent) => Promise<QaResolvedSessionPolicy | undefined>) | undefined, 
+    capabilityPolicy?: ((owner: {
+        readonly id: string;
+    } | undefined, sessionId: string, agent: Agent) => Promise<QaResolvedSessionPolicy | undefined>) | undefined, 
     /** Scope-local catalog entries may be known before they are activated. */
     knownDynamicToolNames?: () => readonly string[]);
     /**
@@ -92,6 +106,20 @@ export declare class QaPolicyAdmission {
      * Source preview asks for the same root, so one upload is readable by both.
      */
     attachmentRoot(): string | undefined;
+    /**
+     * Carry the fence's attachment exemption into the document pipeline.
+     *
+     * The guard above lets a single-file read reach the mounted store: an upload
+     * is content-addressed, immutable, outside every workspace, and the prompt
+     * hands the model exactly that path. The document pipeline keeps its own
+     * read scope and knew nothing about the store, so `document_*` refused the
+     * very file the model was allowed to read — the panel's own Word preview hit
+     * the same wall. The grant is the missing hand-over, made where the access it
+     * mirrors is made: per admitted session, and revoked with it.
+     */
+    private grantDocumentInputRoots;
+    /** Drop one session's document grant, if the pipeline still holds it. */
+    private revokeDocumentInputRoots;
     /**
      * The live agent for one session, resuming a Session the Host has not
      * materialized in this process.
@@ -127,6 +155,29 @@ export declare class QaPolicyAdmission {
      */
     private accessOwner;
     secureSession(token: string, sessionId: string): Promise<QaLockdownProof>;
+    /**
+     * The same admission for a caller whose account was already authenticated by
+     * another credential — the integration API, which has a service token and no
+     * browser session.
+     *
+     * Everything after identity is shared with {@link secureSession}: the
+     * policy pins, the tool allow-list, the QA tool attachment and the
+     * attestation record are one code path, because a second copy of admission
+     * would be a second place for a QA chat to be admitted without them.
+     *
+     * @param userId - the account the credential resolved to.
+     * @param sessionId - the session to attest.
+     * @returns the sanitized proof, as the browser path receives it.
+     */
+    secureSessionForUser(userId: string, sessionId: string): Promise<QaLockdownProof>;
+    /**
+     * The account behind one session, taken from the ownership record rather
+     * than from a token. The record is the same authority the token path reads:
+     * a chat belongs to exactly one account, and a service token may only ever
+     * reach the chats of its own.
+     */
+    private ownerById;
+    private secureSessionAs;
     /**
      * Mask one agent down to the policy's tool names, for the account-free path
      * (a capability policy installs its own mask through its grants).

package/lib/types/shared/documents.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Formats the files panel previews by conversion instead of by bytes.
+ *
+ * Shared by the Host half (which owns the conversion) and the browser card
+ * (which decides whether opening a file should ask for one), so the two cannot
+ * drift on what "we can render this" means. Dependency-free on purpose: the
+ * card bundle inlines it.
+ */
+/** OOXML word-processing documents, as the deployment detects them. */
+export declare const QA_WORD_MEDIA_TYPE = "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+/** The media type of the PDF a converted document arrives as. */
+export declare const QA_PDF_MEDIA_TYPE = "application/pdf";
+/**
+ * Whether the panel asks the Host for a converted PDF rather than rendering the
+ * bytes it already holds. Word documents are the whole set: the document
+ * pipeline reads them and renders PDF, while its other inputs are already
+ * previewable (Markdown as text, PDF through the browser's own viewer).
+ */
+export declare function isConvertibleDocument(mediaType: string): boolean;
+//# sourceMappingURL=documents.d.ts.map

package/lib/types/shared/integration-tokens.d.ts

@@ -0,0 +1,24 @@
+import type { QaServiceTokenScope } from "../types.js";
+/**
+ * The integration-token vocabulary and its bounds, on the browser side too.
+ *
+ * Minting lives in `accounts/service-token.ts`, which is Host-only (it hashes a
+ * secret before storing it); the profile page has to name the same scopes and
+ * enforce the same limits without importing that. Dependency-free like every
+ * `src/shared` module, so both bundles inline it and there is exactly one copy
+ * of the numbers the two halves have to agree on.
+ */
+/**
+ * What an integration token may do. Scopes are checked per request rather than
+ * per deployment: the same bridge token that asks questions carries no
+ * permission to read back a conversation catalog it was not given.
+ */
+export declare const QA_SERVICE_TOKEN_SCOPES: readonly QaServiceTokenScope[];
+/** A token that carries no scope is useless; `ask` is what the API is for. */
+export declare const QA_SERVICE_TOKEN_DEFAULT_SCOPES: readonly QaServiceTokenScope[];
+/** Bounds the caller's label; it is a note to the operator, not a document. */
+export declare const QA_SERVICE_TOKEN_LABEL_MAX = 80;
+/** Bounds on a token's life; zero or a negative TTL would mint a dead token. */
+export declare const QA_SERVICE_TOKEN_TTL_DAYS_MIN = 1;
+export declare const QA_SERVICE_TOKEN_TTL_DAYS_MAX = 3650;
+//# sourceMappingURL=integration-tokens.d.ts.map