@yadsh/dsh-qa-surface 0.18.0 → 0.20.0

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

@@ -1,3 +1,4 @@
+import type { CodeFilesOptions } from "./code-files.js";
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { QaToolDescriptor } from "./types.js";
 import type { QaFormGate } from "../forms/gate.js";
@@ -9,11 +10,11 @@ import type { QaFormGate } from "../forms/gate.js";
  *
  * Bump it whenever the catalog's tool set or their schemas change.
  */
-export declare const QA_TOOL_CATALOG_VERSION = "4";
+export declare const QA_TOOL_CATALOG_VERSION = "5";
 /** What the catalog's definitions read, beyond the execution record. */
-export interface QaToolsSelfcheckDeps {
+export interface QaToolsSelfcheckDeps extends CodeFilesOptions {
     readonly forms?: QaFormGate;
-    readonly formProjection?: (submission: import("../forms/types.js").QaFormSubmission) => Promise<unknown>;
+    readonly formProjection?: (submission: import("../forms/types.js").QaFormSubmission, sessionId: string) => Promise<unknown>;
     readonly catalogVersion: string;
     readonly activationMode: string;
     /** Names the catalog contributes, in catalog order. */

package/lib/types/qa-tools/code-files.d.ts

@@ -0,0 +1,59 @@
+import { type CodeSource, type CodeSourcesCatalog } from "@yadsh/dsh-plugin-kit/code-sources";
+export interface CodeExecution {
+    readonly agent?: {
+        readonly session?: {
+            readonly id?: unknown;
+            readonly header?: {
+                readonly cwd?: unknown;
+            };
+        };
+    };
+}
+export interface CodeFilesOptions {
+    readonly codeSources?: ((exec?: CodeExecution) => CodeSourcesCatalog) | undefined;
+    readonly codeReadRoots?: (() => readonly string[]) | undefined;
+}
+export interface CodeScope {
+    readonly source: CodeSource;
+    readonly root: string;
+}
+/** Selection and authorization are separate, including after following root links. */
+export declare function codeScope(options: CodeFilesOptions, exec: CodeExecution, requested?: unknown): Promise<CodeScope>;
+export declare function boundedInteger(value: unknown, fallback: number, max: number): number;
+/** Read a bounded window, with the selected identity on every result. */
+export declare function readCode(scope: CodeScope, args: {
+    path?: unknown;
+    from?: unknown;
+    lines?: unknown;
+}): Promise<{
+    source: string;
+    label: string;
+    root: string;
+    path: string;
+    absolutePath: string;
+    from: number;
+    to: number;
+    totalLines: number;
+    text: string;
+    truncated: boolean;
+}>;
+/** Literal search in one tree; entry, file, content, time and output budgets are fixed. */
+export declare function searchCode(scope: CodeScope, args: {
+    query?: unknown;
+    path?: unknown;
+    limit?: unknown;
+}): Promise<{
+    source: string;
+    label: string;
+    root: string;
+    query: string;
+    hits: {
+        path: string;
+        line: number;
+        text: string;
+    }[];
+    filesScanned: number;
+    skipped: number;
+    truncated: boolean;
+}>;
+//# sourceMappingURL=code-files.d.ts.map

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

@@ -0,0 +1,7 @@
+import { type ToolDefinition } from "@deepseek-ai/dsh-tools";
+import { type CodeFilesOptions } from "./code-files.js";
+/** Discovery reports availability in this session without granting new roots. */
+export declare function createCodeSourcesTool(options: CodeFilesOptions): ToolDefinition;
+export declare function createCodeReadTool(options: CodeFilesOptions): ToolDefinition;
+export declare function createCodeSearchTool(options: CodeFilesOptions): ToolDefinition;
+//# sourceMappingURL=code-tools.d.ts.map

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

@@ -1,4 +1,5 @@
 import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import { type CodeSourcesCatalog } from "@yadsh/dsh-plugin-kit/code-sources";
 /**
  * `docs_search` and `docs_read` — the documentation surface of the QA catalog.
  *
@@ -73,6 +74,7 @@ interface QaDocsExecution {
  * comes from configuration instead of from the calling chat.
  */
 export interface QaDocsOptions {
+    readonly codeSources?: ((exec?: import("./code-files.js").CodeExecution) => CodeSourcesCatalog) | undefined;
     /** Absolute documentation root, or `""` for `<chat workspace>/docs`. */
     readonly root?: string;
     /**
@@ -112,6 +114,7 @@ export interface QaDocsHit extends QaDocsIdentity {
 }
 /** The outcome of one documentation search. */
 export interface QaDocsSearchResult extends QaDocsIdentity {
+    readonly source?: string;
     readonly query: string;
     /** The directory documentation is read from, relative to the workspace. */
     readonly root: string;
@@ -122,6 +125,7 @@ export interface QaDocsSearchResult extends QaDocsIdentity {
 }
 /** The outcome of one documentation read. */
 export interface QaDocsReadResult extends QaDocsIdentity {
+    readonly source?: string;
     readonly path: string;
     /** Actual read target, kept out of the model-facing rendering. */
     readonly absolutePath: string;

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

@@ -3,9 +3,11 @@ import type { Context } from "@deepseek-ai/cordis";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
 import type { QaToolActivation } from "./types.js";
 export interface QaToolsOptions {
+    readonly codeSources?: import("./code-files.js").CodeFilesOptions["codeSources"];
+    readonly codeReadRoots?: () => readonly string[];
     readonly forms?: import("../forms/gate.js").QaFormGate;
     readonly formsEnabled?: () => boolean;
-    readonly formProjection?: (submission: import("../forms/types.js").QaFormSubmission) => Promise<unknown>;
+    readonly formProjection?: (submission: import("../forms/types.js").QaFormSubmission, sessionId: string) => Promise<unknown>;
     readonly logger: PluginLogger;
     readonly dynamicActivation: boolean;
     readonly activationSkill: string;

package/lib/types/qa-tools/request-user-form.d.ts

@@ -1,5 +1,5 @@
 import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
 import type { QaFormGate } from "../forms/gate.js";
 /** Build only; the QA activation manager owns registration and role admission. */
-export declare function createRequestUserFormTool(gate: QaFormGate, project?: (submission: import("../forms/types.js").QaFormSubmission) => Promise<unknown>): ToolDefinition;
+export declare function createRequestUserFormTool(gate: QaFormGate, project?: (submission: import("../forms/types.js").QaFormSubmission, sessionId: string) => Promise<unknown>): ToolDefinition;
 //# sourceMappingURL=request-user-form.d.ts.map

package/lib/types/request-scheduler.d.ts

@@ -0,0 +1,47 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { QaQueueStatus } from "./types.js";
+/** A FIFO admission lease covers a complete root turn, including its experts. */
+export declare class QaRequestScheduler {
+    private readonly limit;
+    private readonly roots;
+    private readonly now;
+    private readonly familyBusy;
+    private readonly overrideLimit;
+    private readonly active;
+    private readonly waiting;
+    private readonly completed;
+    private readonly retiring;
+    private closed;
+    /**
+     * @param limit - the deployment's ceiling, the chain's last layer.
+     * @param roots - the root agents the queue gates.
+     * @param now - the clock, injectable for the wait estimate's tests.
+     * @param familyBusy - whether a root's descendants still answer.
+     * @param overrideLimit - the ceiling one specific turn fills against, when
+     *   its role or account overrides the deployment's number. `undefined`
+     *   defers to `limit`; this is read per admission, so a settings write is
+     *   visible to the next turn without reloading the plugin.
+     */
+    constructor(limit: () => number, roots: () => readonly Agent[], now?: () => number, familyBusy?: (agent: Agent) => boolean, overrideLimit?: (agent: Agent) => number | undefined);
+    /** The effective ceiling one arriving turn is measured against. */
+    private limitFor;
+    install(ctx: Context): () => void;
+    acquire(agent: Agent, signal: AbortSignal): Promise<void>;
+    release(agent: Agent, completed?: boolean): void;
+    private pump;
+    /**
+     * Report admission as one read sees it.
+     * @param sessionId - the chat whose FIFO position is asked, if any.
+     * @param ceiling - the effective ceiling of the principal this read is for,
+     *   when the caller has resolved it; the deployment's number otherwise.
+     */
+    status(sessionId?: string, ceiling?: number): QaQueueStatus;
+    private estimate;
+    dispose(): void;
+}
+/** Include background descendants whose root has already ended its own turn. */
+export declare function qaRequestFamilyBusy(ctx: Context, root: Agent): boolean;
+/** Older optional compositions may lack the registry, but cannot enforce a cap. */
+export declare function qaRequestRoots(ctx: Context, required: boolean): readonly Agent[];
+//# sourceMappingURL=request-scheduler.d.ts.map

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

@@ -1,5 +1,6 @@
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { Context } from "@deepseek-ai/cordis";
+import { type QaAttachmentRecovery } from "./attachment-access.js";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
 import { type QaSessionFacts } from "./accounts/store.js";
 import type { QaIntegrationPrincipalBindings } from "./integration-principals.js";
@@ -71,13 +72,10 @@ export declare class QaPolicyAdmission {
      * one set answers for the whole chat.
      */
     private readonly attested;
+    private readonly rejected;
     private readonly questionWarnings;
     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;
+    private readonly attachmentAccess;
     /**
      * Every name reachable anywhere in one QA conversation, keyed by session id.
      *
@@ -116,7 +114,7 @@ export declare class QaPolicyAdmission {
      * deliberately not a delegation); {@link secureSessionForUser} has no token
      * to compare, so it fills it here, against the ownership record it checked.
      */
-    principals?: QaIntegrationPrincipalBindings | undefined);
+    principals?: QaIntegrationPrincipalBindings | undefined, attachmentRecovery?: QaAttachmentRecovery);
     /**
      * Add tools whose own executor resolves the QA principal server-side.
      * Enabling the contributing plugin is the operator decision; model arguments
@@ -130,29 +128,17 @@ export declare class QaPolicyAdmission {
      * newly-created, permanently unusable chat behind.
      */
     preflightDeployment(): void;
+    /** Keep a failed creation fenced even when its Host teardown cannot finish. */
+    rejectSession(sessionId: string): void;
+    /** Called only after failed creation confirms resource and ownership cleanup. */
+    forgetRejectedSession(sessionId: string): void;
     /**
-     * The mounted attachment store's verbatim root, when the backend exposes
-     * one. It sits outside every workspace, so the per-user fence would
-     * otherwise deny the model the exact file an upload produced and the prompt
-     * points it at. A backend without a resolvable root simply keeps the fence
-     * closed — attachments then only work where reads are not fenced per user.
-     * Source preview asks for the same root, so one upload is readable by both.
+     * The backend location used to validate exact file capabilities. The root
+     * itself grants no read access; only this conversation's Host-admitted
+     * user-message references and verified submitted form resources do.
      */
     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;
+    grantAttachmentFile(sessionId: string, file: string): void;
     /**
      * The live agent for one session, resuming a Session the Host has not
      * materialized in this process.

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

@@ -0,0 +1,29 @@
+import type { Context } from "@deepseek-ai/cordis";
+import type { PluginLogger } from "@yadsh/dsh-plugin-log";
+import type { QaStoredSessionEraser } from "./admin/session-log.js";
+import type { QaSessionModelPolicy } from "./access/model-policy.js";
+import type { ResolvedQaSurfaceConfig } from "./types.js";
+export interface QaSessionCreateOptions {
+    readonly ctx: Context;
+    readonly config: ResolvedQaSurfaceConfig;
+    readonly logger: PluginLogger;
+    readonly sessionFiles: QaStoredSessionEraser;
+    reserve(id: string): {
+        readonly id: string;
+    } | undefined;
+    release(owner: string, id: string): void;
+    modelPolicy(id: string): QaSessionModelPolicy;
+    preflight(): void;
+    admit(id: string): Promise<unknown>;
+    attest(id: string, owner: string | undefined): void;
+    reject(id: string): void;
+    /** Drop failure-only metadata after resource and ownership cleanup succeeds. */
+    forget(id: string): void;
+}
+/**
+ * Admit inside the native factory's serial publication callback. A failure is
+ * rolled back by the Host's lifecycle owner before we erase this UUID's log;
+ * native preset composition and dynamic default-model hooks stay intact.
+ */
+export declare function createQaSession(options: QaSessionCreateOptions): Promise<string>;
+//# sourceMappingURL=session-create.d.ts.map

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

@@ -1,8 +1,11 @@
 import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
 import type { SessionId } from "@deepseek-ai/dsh-session/types";
 import type { PluginLogger } from "@yadsh/dsh-plugin-log";
-import { type QaSessionModelPolicy } from "./access/model-policy.js";
-import type { QaModelPair } from "./types.js";
+import { type ModelSelectionFacts, type QaSessionModelPolicy } from "./access/model-policy.js";
+import type { QaModelPair, QaModelReplacement } from "./types.js";
+/** Host selection is durable and can differ from immutable agent creation options. */
+export declare function sessionModelSelection(ctx: Context, agent: Pick<Agent, "session" | "options">): ModelSelectionFacts;
 /**
  * Put one fresh session on the pair its model policy names.
  *
@@ -21,4 +24,10 @@ import type { QaModelPair } from "./types.js";
  * @returns the pair the session was put on, or `undefined` when none applied.
  */
 export declare function applySessionModelPolicy(ctx: Context, sessionId: SessionId, policy: QaSessionModelPolicy, logger: PluginLogger): Promise<QaModelPair | undefined>;
+/** Migrate an idle owned chat only along an explicit redirect to its exact policy. */
+export declare function reconcileSessionModelPolicy(ctx: Context, sessionId: SessionId, policy: QaSessionModelPolicy, current: {
+    readonly status: string;
+    readonly options: ModelSelectionFacts;
+    readonly runMaintenance?: Agent["runMaintenance"];
+}, replacements: readonly QaModelReplacement[], logger: PluginLogger): Promise<boolean>;
 //# sourceMappingURL=session-model.d.ts.map

package/lib/types/shared/history-folder.d.ts

@@ -0,0 +1,4 @@
+import type { QaHistoryFolderTarget } from "../types/accounts.js";
+/** Bound both fields at the server boundary; identifiers are opaque UI keys. */
+export declare function normalizeHistoryFolder(input: unknown): QaHistoryFolderTarget | null;
+//# sourceMappingURL=history-folder.d.ts.map

package/lib/types/types/accounts.d.ts

@@ -128,12 +128,22 @@ export interface QaClaimResult {
  * questions cannot read back conversations it was never given.
  */
 export type QaServiceTokenScope = "ask" | "sessions:read";
+/** Virtual UI destination, never a workspace or filesystem path. */
+export interface QaHistoryFolderTarget {
+    readonly id: string;
+    readonly name: string;
+}
+export interface QaOwnedSessionsResult {
+    readonly ids: readonly string[];
+    readonly integrationFolders?: Readonly<Record<string, QaHistoryFolderTarget>>;
+}
 /**
  * What an account asks a new integration token to be. The credential is always
  * issued to the caller: nothing a browser sends may name another account, so
  * this shape has no owner field and the administrative path keeps its own.
  */
 export interface QaServiceTokenCreateInput {
+    readonly historyFolder?: QaHistoryFolderTarget | null;
     /** A note the operator's list shows; empty becomes a generic label. */
     readonly label?: string;
     /** Requested scopes; unknown ones are dropped, explicit empty grants none. */
@@ -149,6 +159,7 @@ export interface QaServiceTokenCreateInput {
  * that could repeat it would be a list that leaks it.
  */
 export interface QaServiceTokenSummary {
+    readonly historyFolder?: QaHistoryFolderTarget | null;
     readonly id: string;
     readonly label: string;
     readonly scopes: readonly QaServiceTokenScope[];

package/lib/types/types/capability.d.ts

@@ -120,8 +120,7 @@ export interface QaSkillActivationRecord {
     readonly reason?: string;
 }
 /**
- * One provider and model pair, fixed by policy rather than chosen in the
- * interface. `provider` and `model` are named together or not at all, because
+ * One provider and model pair. `provider` and `model` are named together, because
  * the Host refuses either of them alone.
  */
 export interface QaModelPair {
@@ -129,6 +128,11 @@ export interface QaModelPair {
     readonly model: string;
     readonly reasoningEffort?: string;
 }
+/** Operator-defined replacement of one exact provider/model pair. */
+export interface QaModelReplacement {
+    readonly from: QaModelPair;
+    readonly to: QaModelPair;
+}
 /** One agent capability profile. It never grants administrative access. */
 export interface QaSubrole {
     readonly id: string;
@@ -137,11 +141,19 @@ export interface QaSubrole {
     readonly enabled: boolean;
     readonly capabilities: QaCapabilitySelection;
     /**
-     * The pair every chat of this role is opened on, whatever the visitor picks
-     * in the interface. Absent means the role keeps no opinion and the
+     * The default pair every new chat of this role opens on.
+     * Absent means the role keeps no opinion and the
      * deployment's pair serves it.
      */
     readonly model?: QaModelPair;
+    /** Additional user-selectable pairs. The default model stays available. */
+    readonly allowedModels?: readonly QaModelPair[];
+    /**
+     * How many of the stand's slots this role's turns may fill at once, ahead of
+     * the deployment's `session.maxActiveRequests`. 0 lifts the ceiling for this
+     * role's turns; absent keeps the deployment's number.
+     */
+    readonly maxActiveRequests?: number;
     readonly ui?: {
         readonly icon?: string;
         readonly accent?: string;
@@ -178,6 +190,21 @@ export interface QaUserAccess {
      * deployment shares. Absent means the account keeps no opinion.
      */
     readonly model?: QaModelPair;
+    /** Overrides the role's alternatives; [] permits only the default model. */
+    readonly allowedModels?: readonly QaModelPair[];
+    /**
+     * How many of the stand's slots this account's turns may fill at once,
+     * ahead of what its role says. 0 lifts the ceiling for this account's
+     * turns; absent keeps the role's or the deployment's number.
+     */
+    readonly maxActiveRequests?: number;
+}
+/** Filtered model choices for one owned chat or the caller's next chat. */
+export interface QaModelOptions {
+    readonly models: readonly QaModelCatalogEntry[];
+    readonly choices: readonly QaModelPair[];
+    readonly defaultModel?: QaModelPair;
+    readonly selected?: QaModelPair;
 }
 export type QaCapabilitySourceKind = "core" | "plugin" | "mcp" | "filesystem" | "runtime";
 /** One capability currently installed, or retained as a missing selection. */

package/lib/types/types/code-sources.d.ts

@@ -0,0 +1,12 @@
+/** Browser-safe source selection state; filesystem access is configured separately. */
+export interface QaChatCodeSources {
+    readonly selectedSource: string | null;
+    readonly effectiveSource: string | null;
+    readonly entries: readonly {
+        readonly id: string;
+        readonly label: string;
+    }[];
+    readonly writable: boolean;
+    readonly unavailable: boolean;
+}
+//# sourceMappingURL=code-sources.d.ts.map

package/lib/types/types/config.d.ts

@@ -1,4 +1,6 @@
 import type { QaAccountIdentityField } from "./accounts.js";
+import type { QaModelReplacement } from "./capability.js";
+import type { CodeSourcesConfig, CodeSourcesCatalog } from "@yadsh/dsh-plugin-kit/code-sources";
 import type { QaApprovalInteraction, QaApprovalPolicy, QaQuestionInteraction, QaQuestionInteractionInput, QaSandboxMode, QaSessionPolicy, QaToolActivationMode, QaToolPolicyMode } from "./policy.js";
 import type { QaSlashCommandsConfig, ResolvedQaSlashCommands } from "./slash.js";
 export interface QaSourcesConfig {
@@ -94,6 +96,8 @@ export interface QaNotesConfig {
     };
 }
 export interface QaSurfaceConfig {
+    /** Named code trees shared with Git; access is granted separately. */
+    readonly codeSources?: CodeSourcesConfig;
     readonly forms?: Partial<import("../forms/types.js").QaFormPolicy>;
     readonly enabled?: boolean;
     readonly route?: {
@@ -120,6 +124,8 @@ export interface QaSurfaceConfig {
         readonly provider?: string | null;
         readonly model?: string | null;
         readonly reasoningEffort?: string | null;
+        /** Exact central redirects applied after account/role/deployment precedence. */
+        readonly modelReplacements?: readonly QaModelReplacement[];
         /**
          * How many chat turns the deployment answers at once. A ceiling is what a
          * locally hosted model needs: the card runs out long before the queue does,
@@ -274,6 +280,11 @@ export interface QaSurfaceConfig {
             readonly enabled?: boolean;
             /** Directory below the personal root; relative, never escaping it. */
             readonly relativeRoot?: string;
+            /** Copy only these deployment skills into shared storage once. */
+            readonly sharedSeed?: {
+                readonly root: string;
+                readonly names: readonly string[];
+            } | null;
             /** Follow manual file edits and refresh the DSH catalog. */
             readonly watch?: boolean;
             readonly maxSkillBytes?: number;
@@ -347,6 +358,8 @@ export interface QaIntegrationConfig {
     readonly maxRequestBytes?: number;
     /** Ceiling on one inline image attachment, in bytes. */
     readonly maxAttachmentBytes?: number;
+    /** Files per integration request; 0 inherits attachments.maxPending. */
+    readonly maxAttachments?: number;
     /**
      * Ceiling on the published answer, in characters. The caller posts it into a
      * ticket comment, whose own budget is smaller than a model's answer, and a
@@ -375,6 +388,7 @@ export interface QaAttachmentsConfig {
     readonly extensions?: readonly string[];
 }
 export interface ResolvedQaSurfaceConfig {
+    readonly codeSources: CodeSourcesCatalog;
     readonly forms: Readonly<import("../forms/types.js").QaFormPolicy>;
     readonly enabled: boolean;
     readonly route: {
@@ -399,6 +413,7 @@ export interface ResolvedQaSurfaceConfig {
         readonly provider: string | null;
         readonly model: string | null;
         readonly reasoningEffort: string | null;
+        readonly modelReplacements: readonly QaModelReplacement[];
         readonly maxActiveRequests: number;
     };
     readonly ui: {
@@ -477,6 +492,10 @@ export interface ResolvedQaSurfaceConfig {
         skills: {
             readonly enabled: boolean;
             readonly relativeRoot: string;
+            readonly sharedSeed: {
+                readonly root: string;
+                readonly names: readonly string[];
+            } | null;
             readonly watch: boolean;
             readonly maxSkillBytes: number;
             readonly allowResourceEditing: boolean;
@@ -597,6 +616,7 @@ export interface ResolvedQaSurfaceConfig {
         readonly requestsPerMinute: number;
         readonly maxRequestBytes: number;
         readonly maxAttachmentBytes: number;
+        readonly maxAttachments: number;
         readonly maxAnswerCharacters: number;
     };
 }

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

@@ -331,6 +331,14 @@ export interface QaQueueStatus {
     readonly active: number;
     /** Whether one more turn fits; false while no ceiling is set. */
     readonly full: boolean;
+    /** The Host enforces admission and starts queued turns automatically. */
+    readonly managed?: boolean;
+    readonly queued?: number;
+    /** Present only for the authorized chat whose status was requested. */
+    readonly waiting?: boolean;
+    readonly position?: number | null;
+    /** Approximate delay derived from completed turns, or null without a sample. */
+    readonly estimatedWaitMs?: number | null;
 }
 export interface QaSessionState {
     readonly chatAccess?: import("../chat-sharing/types.js").QaChatAccess;

package/lib/types/types.d.ts

@@ -10,6 +10,7 @@ export type * from "./types/config.js";
 export type * from "./types/slash.js";
 export type * from "./types/documents.js";
 export type * from "./types/session.js";
+export type * from "./types/code-sources.js";
 export type * from "./types/answer-review.js";
 export type * from "./types/quality.js";
 export type * from "./types/admin.js";

package/lib/types/user-workspace.d.ts

@@ -10,6 +10,8 @@ export interface QaToolExecutionLike {
 export interface QaUserWorkspaceReadPolicy {
     /** Shared directories exposed only to read-only filesystem tools. */
     readonly sharedReadOnlyRoots?: readonly string[];
+    /** Exact canonical files derived from this conversation's trusted references. */
+    readonly attachmentFiles?: readonly string[];
 }
 export declare function pathIsInside(target: string, root: string): boolean;
 /**
@@ -31,12 +33,8 @@ export declare function existingQaUserWorkspace(workspaceRoot: string, userId: s
  * fences model-controlled file paths for both reads and writes, rejects tools
  * whose implementation can walk above cwd, and enforces bounded scratch use.
  *
- * `attachmentRoot` is the one deliberate read exemption: an uploaded file is
- * an immutable content-addressed copy the deployment stores outside every
- * workspace, and the model reaches it exactly as the harness intends (the
- * prompt carries the stored path). Reads of a single such file are allowed;
- * directory-wide tools stay confined because the store is shared by every
- * account, and writes are never exempted.
+ * `attachmentRoot` identifies the storage backend, never authority to read it.
+ * Only regular files in `attachmentFiles` may cross the workspace boundary.
  */
 export declare function qaUserWorkspaceDenial(execution: QaToolExecutionLike, root: string, attachmentRoot?: string, readPolicy?: QaUserWorkspaceReadPolicy): string | undefined;
 //# sourceMappingURL=user-workspace.d.ts.map