@deepseek-ai/dsh-tool-session-query 0.0.1-rc.1

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-tool-session-query`.
+* @module @deepseek-ai/dsh-tool-session-query/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-session-query";
+/** Cordis companion plugin name. */
+const name = "tool-session-query-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this read-only model adapter owns no event or mutable
+* data relationship beyond the registries that already validate registration.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Model-facing, workspace-authorized session-history search and read tools.
+ *
+ * @module @deepseek-ai/dsh-tool-session-query
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Cordis plugin name used by Loader diagnostics. */
+export declare const name = "tool-session-query";
+/** Capability services required by the model-facing consumer. */
+export declare const inject: string[];
+/** Default maximum number of authorized search hits returned by one call. */
+export declare const DEFAULT_MAX_SEARCH_RESULTS = 100;
+/** Default cooperative deadline for either full-text search tool. */
+export declare const DEFAULT_SEARCH_TIMEOUT_MS = 30000;
+/** Deployment-owned search count and timeout bounds. */
+export interface Config {
+    /** Maximum authorized hits returned by one search call. Defaults to 100. */
+    maxSearchResults?: number;
+    /** Cooperative full-text search deadline in milliseconds. Defaults to 30000. */
+    searchTimeoutMs?: number;
+}
+/** Schemastery config for Loader defaults and generated configuration docs. */
+export declare const Config: z<Config>;
+/** Register all five tools and their shared model guidance. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/input.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Model argument schemas, normalization, and filter construction.
+ *
+ * @module @deepseek-ai/dsh-tool-session-query/input
+ */
+import { type SessionId as SessionIdValue } from '@deepseek-ai/dsh-session';
+import { type SessionAvailability, type SessionEventMetadataFilter, type SessionEventSurface, type SessionResultFilter } from '@deepseek-ai/dsh-session-query';
+interface SessionSearchArgs {
+    query: string;
+    session_ids?: string[];
+    created_at_from?: string;
+    created_at_to?: string;
+    parent_session_ids?: string[];
+    include_root_sessions?: boolean;
+    availability?: SessionAvailability[];
+    event_seq_from?: number;
+    event_seq_to?: number;
+    event_time_from?: string;
+    event_time_to?: string;
+    event_types?: string[];
+    event_surfaces?: SessionEventSurface[];
+}
+interface EventFilterInput {
+    readonly seqFrom?: number | undefined;
+    readonly seqTo?: number | undefined;
+    readonly timeFrom?: string | undefined;
+    readonly timeTo?: string | undefined;
+    readonly eventTypes?: string[] | undefined;
+    readonly surfaces?: SessionEventSurface[] | undefined;
+}
+declare function buildSessionFilters(args: SessionSearchArgs): SessionResultFilter[];
+declare function materializeParentSessionIds(values: readonly string[] | undefined): SessionIdValue[] | undefined;
+declare function buildEventFilters(input: EventFilterInput): SessionEventMetadataFilter[];
+declare function normalizeQuery(value: string): string;
+declare function sequenceRange(from: number | undefined, to: number | undefined): {
+    from?: number;
+    to?: number;
+};
+declare function assertNonNegativeSafeInteger(name: string, value: number): void;
+/** Model schemas and model-owned value normalization shared by tool operations. */
+export declare const toolInput: {
+    sessionSearchParameters: {
+        readonly query: {
+            readonly type: "string";
+            readonly required: true;
+            readonly description: "Literal full-text query over prior session history.";
+        };
+        readonly session_ids: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Optional session ids to include.";
+        };
+        readonly created_at_from: {
+            readonly type: "string";
+            readonly description: "Inclusive timezone-qualified ISO 8601 creation-time lower bound.";
+        };
+        readonly created_at_to: {
+            readonly type: "string";
+            readonly description: "Inclusive timezone-qualified ISO 8601 creation-time upper bound.";
+        };
+        readonly parent_session_ids: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Optional direct parent session ids.";
+        };
+        readonly include_root_sessions: {
+            readonly type: "boolean";
+            readonly description: "Include sessions with no parent in the parent filter.";
+        };
+        readonly availability: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly enum: readonly ["live", "persisted"];
+            };
+            readonly description: "Require at least one selected source availability.";
+        };
+        readonly event_seq_from: {
+            readonly type: "integer";
+            readonly description: "Inclusive event sequence lower bound.";
+        };
+        readonly event_seq_to: {
+            readonly type: "integer";
+            readonly description: "Inclusive event sequence upper bound.";
+        };
+        readonly event_time_from: {
+            readonly type: "string";
+            readonly description: "Inclusive timezone-qualified ISO 8601 event-time lower bound.";
+        };
+        readonly event_time_to: {
+            readonly type: "string";
+            readonly description: "Inclusive timezone-qualified ISO 8601 event-time upper bound.";
+        };
+        readonly event_types: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Event types to include.";
+        };
+        readonly event_surfaces: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly enum: readonly ["current", "shadowed", "log-only"];
+            };
+            readonly description: "Event surfaces to include.";
+        };
+    };
+    eventSearchParameters: {
+        readonly session_id: {
+            readonly type: "string";
+            readonly description: "Target session id. Omit for the current session.";
+        };
+        readonly query: {
+            readonly type: "string";
+            readonly required: true;
+            readonly description: "Literal full-text query over the target session.";
+        };
+        readonly seq_from: {
+            readonly type: "integer";
+            readonly description: "Inclusive event sequence lower bound.";
+        };
+        readonly seq_to: {
+            readonly type: "integer";
+            readonly description: "Inclusive event sequence upper bound.";
+        };
+        readonly time_from: {
+            readonly type: "string";
+            readonly description: "Inclusive timezone-qualified ISO 8601 event-time lower bound.";
+        };
+        readonly time_to: {
+            readonly type: "string";
+            readonly description: "Inclusive timezone-qualified ISO 8601 event-time upper bound.";
+        };
+        readonly event_types: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Event types to include.";
+        };
+        readonly surfaces: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly enum: readonly ["current", "shadowed", "log-only"];
+            };
+            readonly description: "Event surfaces to include.";
+        };
+    };
+    targetSessionParameter: {
+        readonly session_id: {
+            readonly type: "string";
+            readonly description: "Target session id. Omit for the current session.";
+        };
+    };
+    buildSessionFilters: typeof buildSessionFilters;
+    materializeParentSessionIds: typeof materializeParentSessionIds;
+    buildEventFilters: typeof buildEventFilters;
+    normalizeQuery: typeof normalizeQuery;
+    sequenceRange: typeof sequenceRange;
+    assertNonNegativeSafeInteger: typeof assertNonNegativeSafeInteger;
+};
+export {};
+//# sourceMappingURL=input.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-session-query`.
+ * @module @deepseek-ai/dsh-tool-session-query/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-session-query-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/operations.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Tool operation orchestration over session-query service capabilities.
+ *
+ * @module @deepseek-ai/dsh-tool-session-query/operations
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SessionEventSurface } from '@deepseek-ai/dsh-session-query';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+import { toolInput } from './input.ts';
+type SessionSearchArgs = Parameters<typeof toolInput.buildSessionFilters>[0];
+interface EventSearchArgs {
+    session_id?: string;
+    query: string;
+    seq_from?: number;
+    seq_to?: number;
+    time_from?: string;
+    time_to?: string;
+    event_types?: string[];
+    surfaces?: SessionEventSurface[];
+}
+interface SessionTargetArgs {
+    session_id?: string;
+}
+interface EventTargetArgs extends SessionTargetArgs {
+    seq: number;
+}
+interface EventReadArgs extends EventTargetArgs {
+    before?: number;
+    after?: number;
+}
+declare function executeSessionSearch(ctx: Context, args: SessionSearchArgs, exec: ToolRunContext, maxResults: number): Promise<string>;
+declare function executeEventSearch(ctx: Context, args: EventSearchArgs, exec: ToolRunContext, maxResults: number): Promise<string>;
+declare function executeSessionTrace(ctx: Context, args: SessionTargetArgs, exec: ToolRunContext): Promise<string>;
+declare function executeEventTrace(ctx: Context, args: EventTargetArgs, exec: ToolRunContext): Promise<string>;
+declare function executeEventRead(ctx: Context, args: EventReadArgs, exec: ToolRunContext): Promise<string>;
+/** Five model-facing session-query operation implementations. */
+export declare const operations: {
+    executeSessionSearch: typeof executeSessionSearch;
+    executeEventSearch: typeof executeEventSearch;
+    executeSessionTrace: typeof executeSessionTrace;
+    executeEventTrace: typeof executeEventTrace;
+    executeEventRead: typeof executeEventRead;
+};
+export {};
+//# sourceMappingURL=operations.d.ts.map

package/lib/types/presentation.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Model text rendering and generic tool-call presentation.
+ *
+ * @module @deepseek-ai/dsh-tool-session-query/presentation
+ */
+import { type SessionEventSearchHit, type SessionEventTraceObservation, type SessionEventWindow, type SessionLineageTrace, type SessionRecord, type SessionSearchHit } from '@deepseek-ai/dsh-session-query';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { GenericCallView } from '@deepseek-ai/dsh-tools';
+import { workspaceAccess } from './workspace-access.ts';
+type TitleView = Awaited<ReturnType<typeof workspaceAccess.readTitle>>;
+type CompleteTitleMap = Awaited<ReturnType<typeof workspaceAccess.readTitles>>;
+type AuthorizedDescendants = ReturnType<typeof workspaceAccess.authorizeDescendants>;
+interface SearchCollection<T> {
+    readonly items: T[];
+    readonly capped: boolean;
+}
+interface SessionSearchCallArgs {
+    readonly query: string;
+}
+interface EventSearchCallArgs {
+    readonly query: string;
+}
+interface SessionTargetCallArgs {
+    readonly session_id?: string;
+}
+interface EventTargetCallArgs extends SessionTargetCallArgs {
+    readonly seq: number;
+}
+declare function formatSessionSearch(collected: SearchCollection<SessionSearchHit>, titles: CompleteTitleMap, authorizedParents: ReadonlySet<SessionId>): string;
+declare function formatEmptySessionSearch(): string;
+declare function formatEventSearch(sessionId: SessionId, title: TitleView, collected: SearchCollection<SessionEventSearchHit>): string;
+declare function formatSessionTrace(trace: SessionLineageTrace, ancestors: readonly SessionRecord[], ancestorBoundary: boolean, descendants: AuthorizedDescendants, titles: CompleteTitleMap): string;
+declare function formatEventTrace(sessionId: SessionId, title: TitleView, trace: SessionEventTraceObservation): string;
+declare function formatEventRead(sessionId: SessionId, title: TitleView, window: SessionEventWindow): string;
+declare function presentSessionSearchCall(args: SessionSearchCallArgs): GenericCallView;
+declare function presentEventSearchCall(args: EventSearchCallArgs): GenericCallView;
+declare function presentSessionTraceCall(args: SessionTargetCallArgs): GenericCallView;
+declare function presentEventTargetCall(action: string, args: EventTargetCallArgs): GenericCallView;
+/** Text output and call-card presentation for every session-query tool. */
+export declare const presentation: {
+    formatSessionSearch: typeof formatSessionSearch;
+    formatEmptySessionSearch: typeof formatEmptySessionSearch;
+    formatEventSearch: typeof formatEventSearch;
+    formatSessionTrace: typeof formatSessionTrace;
+    formatEventTrace: typeof formatEventTrace;
+    formatEventRead: typeof formatEventRead;
+    presentSessionSearchCall: typeof presentSessionSearchCall;
+    presentEventSearchCall: typeof presentEventSearchCall;
+    presentSessionTraceCall: typeof presentSessionTraceCall;
+    presentEventTargetCall: typeof presentEventTargetCall;
+};
+export {};
+//# sourceMappingURL=presentation.d.ts.map

package/lib/types/service-boundary.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Session-query service error containment and model-safe translation.
+ *
+ * @module @deepseek-ai/dsh-tool-session-query/service-boundary
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+declare function unauthorizedTarget(): HarnessError;
+declare function call<Value>(ctx: Context, signal: AbortSignal, operation: string, invoke: () => Promise<Value>): Promise<Value>;
+declare function sanitizeError(ctx: Context, operation: string, error: unknown): HarnessError;
+/** Model-safe session-query invocation and error translation boundary. */
+export declare const serviceBoundary: {
+    unauthorizedTarget: typeof unauthorizedTarget;
+    call: typeof call;
+    sanitizeError: typeof sanitizeError;
+};
+export {};
+//# sourceMappingURL=service-boundary.d.ts.map

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

@@ -0,0 +1,61 @@
+/**
+ * Caller identity, workspace authorization, and visible lineage projection.
+ *
+ * @module @deepseek-ai/dsh-tool-session-query/workspace-access
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SessionEvent, type SessionHeader, type SessionId as SessionIdValue } from '@deepseek-ai/dsh-session';
+import type { SessionLineageNode, SessionRecord } from '@deepseek-ai/dsh-session-query';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+interface Caller {
+    readonly id: SessionIdValue;
+    readonly header: SessionHeader;
+    readonly events: readonly SessionEvent[];
+}
+interface TitleView {
+    readonly text: string;
+    readonly unavailableCode?: string;
+}
+interface CompleteTitleMap extends ReadonlyMap<SessionIdValue, TitleView> {
+    get(id: SessionIdValue): TitleView;
+}
+interface AuthorizedDescendant {
+    readonly record: SessionRecord;
+    readonly descendants: Array<AuthorizedDescendant | null>;
+}
+interface DescendantVisit {
+    readonly node: AuthorizedDescendant | null;
+    readonly depth: number;
+    readonly next: DescendantVisit | undefined;
+}
+declare function callerOf(exec: ToolRunContext): Caller;
+declare function targetId(args: {
+    readonly session_id?: string;
+}, caller: Caller): SessionIdValue;
+declare function authorizeTarget(ctx: Context, caller: Caller, target: SessionIdValue, signal: AbortSignal): Promise<void>;
+declare function recordAuthorized(record: SessionRecord, caller: Caller): boolean;
+declare function assertObservedTargetAuthorized(caller: Caller, target: SessionIdValue, observed: SessionHeader): void;
+declare function authorizeSessionIds(ctx: Context, caller: Caller, ids: readonly SessionIdValue[], signal: AbortSignal): Promise<ReadonlySet<SessionIdValue>>;
+declare function readTitles(ctx: Context, caller: Caller, ids: readonly SessionIdValue[], signal: AbortSignal): Promise<CompleteTitleMap>;
+declare function readTitle(ctx: Context, caller: Caller, id: SessionIdValue, signal: AbortSignal): Promise<TitleView>;
+declare function authorizeDescendants(nodes: readonly SessionLineageNode[], caller: Caller): Array<AuthorizedDescendant | null>;
+declare function visitDescendants(nodes: readonly (AuthorizedDescendant | null)[]): Generator<DescendantVisit>;
+declare function descendantIds(nodes: readonly (AuthorizedDescendant | null)[]): SessionIdValue[];
+declare function titleText(view: TitleView): string;
+/** Workspace-scoped caller authorization, title access, and lineage projection. */
+export declare const workspaceAccess: {
+    callerOf: typeof callerOf;
+    targetId: typeof targetId;
+    authorizeTarget: typeof authorizeTarget;
+    recordAuthorized: typeof recordAuthorized;
+    assertObservedTargetAuthorized: typeof assertObservedTargetAuthorized;
+    authorizeSessionIds: typeof authorizeSessionIds;
+    readTitles: typeof readTitles;
+    readTitle: typeof readTitle;
+    authorizeDescendants: typeof authorizeDescendants;
+    visitDescendants: typeof visitDescendants;
+    descendantIds: typeof descendantIds;
+    titleText: typeof titleText;
+};
+export {};
+//# sourceMappingURL=workspace-access.d.ts.map

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@deepseek-ai/dsh-tool-session-query",
+  "description": "Workspace-authorized model-facing session history search, trace, and event read tools",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session-query/tool-session-query"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-query": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-query": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-query-sqlite": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-title": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-timeout-policy": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1"
+  }
+}