@sidequest-007/dsh-atlas 1.0.0

package/lib/types/external.d.ts

@@ -0,0 +1,58 @@
+/** The one sandbox mode that may DISCOVER new external paths. */
+export declare const EXTERNAL_ADDING_MODE = "danger-full-access";
+/** The sandbox modes this plugin understands; anything else is treated as narrow. */
+export type SandboxModeName = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** What one session may do with out-of-workspace paths right now. */
+export interface ExternalAccess {
+    /** Whether this session may reference and search paths the ledger does not know yet. */
+    readonly canDiscover: boolean;
+    /** Ledger directories this session may reference INTO, as canonical paths. */
+    readonly roots: readonly string[];
+    /** Ledger paths this session may reference EXACTLY (files included). */
+    readonly known: readonly string[];
+}
+/** The access a session with no resolved policy gets: ledger paths only. */
+export declare const NO_EXTERNAL_DISCOVERY: ExternalAccess;
+/**
+ * Build one session's access from its resolved sandbox mode and the ledger.
+ * @param mode - the resolved sandbox mode, or undefined when the host has no policy service.
+ * @param roots - ledger directories associated with this workspace.
+ * @param known - every ledger path associated with this workspace, files included.
+ * @returns the access verdict for this session.
+ */
+export declare function externalAccess(mode: string | undefined, roots: readonly string[], known?: readonly string[]): ExternalAccess;
+/**
+ * Whether one absolute path may be referenced under this access.
+ *
+ * A discovering session may reference anything that exists; a narrow one only
+ * what the ledger already holds — the exact paths the user referenced before
+ * (files included) and anything inside the ledger's directories.
+ * @param access - the session's access verdict.
+ * @param absolute - an absolute candidate path.
+ * @returns true when the path is allowed.
+ */
+export declare function allowsExternal(access: ExternalAccess, absolute: string): boolean;
+/**
+ * Whether a path lies inside a directory (the directory itself counts).
+ *
+ * Compares canonical keys and requires a separator boundary, so a sibling whose
+ * name merely starts the same (`…/b` vs `…/bc`) is never treated as inside.
+ * @param root - the containing directory.
+ * @param target - the candidate path.
+ * @returns true when target is root or below it.
+ */
+export declare function isUnder(root: string, target: string): boolean;
+/** The canonical spelling of one external path, as tokens and the ledger carry it. */
+export declare function externalPath(absolute: string): string;
+/**
+ * Whether one path is absolute rather than workspace-relative.
+ *
+ * Both halves need this: the host decides whether a reference escapes the
+ * workspace at all, and the browser half must not look an absolute path up in a
+ * workspace-relative index (it would never be there). A drive-relative spelling
+ * (`E:foo`) is NOT absolute — it names nothing stable, so it stays a relative
+ * path and is refused by the host's own confinement test.
+ * @param value - a path as typed, picked, or recorded.
+ * @returns true for `E:/…`, `E:\…`, `/…`, or a UNC `\\server\share`.
+ */
+export declare function isAbsoluteReference(value: string): boolean;

package/lib/types/files.d.ts

@@ -0,0 +1,76 @@
+import type { Dir } from 'node:fs';
+import type { FileEntry, FileIgnoreRuleInput } from './contract.ts';
+/** Options for one bounded index pass. */
+export interface IndexOptions {
+    /** Hard cap on collected files. */
+    readonly maxFiles: number;
+    /** Directory basenames the walk skips (children never enqueue). */
+    readonly ignoreDirs: readonly string[];
+    /** Exact and Regex basename filters applied before files enter the index. */
+    readonly ignoreFiles: readonly FileIgnoreRuleInput[];
+}
+/** One index pass result: the sorted file list plus the honest truncation flag. */
+export interface WorkspaceIndex {
+    readonly files: readonly FileEntry[];
+    /** True when the walk hit `maxFiles` before the tree was exhausted. */
+    readonly truncated: boolean;
+}
+/** Directory opener seam used by the real filesystem and deterministic tests. */
+export type OpenWorkspaceDirectory = (path: string) => Promise<Dir>;
+/**
+ * Collect every regular file under `root` (bounded, name-sorted).
+ * @param root - workspace root to walk.
+ * @param options - cap and ignore list.
+ * @param signal - caller lifetime; every filesystem await races it.
+ * @param openDirectory - directory opener; defaults to node:fs.
+ * @returns the sorted file list and the truncation flag.
+ */
+export declare function indexWorkspace(root: string, options: IndexOptions, signal?: AbortSignal, openDirectory?: OpenWorkspaceDirectory): Promise<WorkspaceIndex>;
+/**
+ * List the DIRECT subdirectories of one directory (one level, never recursive).
+ *
+ * Used to offer the folders around a session workspace — the sibling checkouts
+ * a plugin author routinely needs, e.g. the DSH source tree beside the workspace
+ * — without walking anything: one `opendir` of one directory. Symlinks are
+ * skipped exactly like the workspace walk skips them (a link cycle can never
+ * strand this), ignore-listed directory names are skipped by basename, and the
+ * bounded result is name-sorted.
+ * @param dir - absolute directory to list.
+ * @param options - cap and the ignored directory basenames.
+ * @param signal - caller lifetime; the filesystem awaits race it.
+ * @param openDirectory - directory opener; defaults to node:fs.
+ * @returns absolute child directory paths, name-sorted and capped.
+ */
+export declare function listSubdirectories(dir: string, options: {
+    readonly limit: number;
+    readonly ignoreDirs: readonly string[];
+    readonly skipHidden?: boolean;
+    readonly followLinks?: boolean;
+}, signal?: AbortSignal, openDirectory?: OpenWorkspaceDirectory): Promise<readonly string[]>;
+/** One row of a one-level directory listing: a name and what it is. */
+export interface DirectoryEntryInfo {
+    readonly name: string;
+    readonly kind: 'file' | 'dir';
+}
+/** One directory's direct children, name-sorted with directories first. */
+export interface DirectoryContents {
+    readonly entries: readonly DirectoryEntryInfo[];
+    /** True when the entry cap cut the listing short. */
+    readonly truncated: boolean;
+}
+/**
+ * List ONE directory's direct children, files included.
+ *
+ * The folder browser and the folder tab need what a file manager shows — both
+ * kinds, in one level — where {@link listSubdirectories} answers "which folders
+ * are next to this one". A link (junction or symlink) is reported as what it
+ * POINTS AT and dropped when it points at nothing, because a row the user cannot
+ * enter is worse than no row. Directories come first, then names, so the shape of
+ * the tree reads before its contents do.
+ * @param dir - absolute directory to list.
+ * @param limit - hard cap on returned entries.
+ * @param signal - caller lifetime; the filesystem awaits race it.
+ * @param openDirectory - directory opener; defaults to node:fs.
+ * @returns the entries and whether the cap was reached.
+ */
+export declare function readDirectory(dir: string, limit: number, signal?: AbortSignal, openDirectory?: OpenWorkspaceDirectory): Promise<DirectoryContents>;

package/lib/types/git.d.ts

@@ -0,0 +1,44 @@
+import type { AtlasProvider } from './atlas.ts';
+import { type GitChange } from './contract.ts';
+/**
+ * Parse porcelain v1 output into changes, dropping ignored directories.
+ * @param output - the raw `git status --porcelain=v1` text.
+ * @returns one entry per changed path, in git's order.
+ */
+export declare function parseGitStatus(output: string): readonly GitChange[];
+/**
+ * Parse `git diff --numstat` output into per-path line counts.
+ * @param output - the raw numstat text.
+ * @returns a path-keyed count map; binary files have no counts and are absent.
+ */
+export declare function parseGitNumstat(output: string): ReadonlyMap<string, {
+    added: number;
+    removed: number;
+}>;
+/**
+ * The workspace's changed paths, with line counts where Git can count them.
+ * @param cwd - the workspace directory.
+ * @param signal - caller lifetime.
+ * @returns the changes, or an empty list outside a Git workspace.
+ */
+export declare function readGitChanges(cwd: string, signal: AbortSignal): Promise<readonly GitChange[]>;
+/**
+ * The diff for one changed path. A path Git sees as unchanged against HEAD is
+ * retried against the empty file, so an untracked path's content arrives as
+ * Git's own "new file" hunk rather than as a file read.
+ * @param cwd - the workspace directory.
+ * @param path - the repository-relative path being committed.
+ * @param signal - caller lifetime.
+ * @returns the diff text, or undefined when Git produced none.
+ */
+export declare function readGitDiff(cwd: string, path: string, signal: AbortSignal): Promise<string | undefined>;
+/**
+ * The built-in `@git` provider's injection half.
+ *
+ * This is the seam's worked example, and it is deliberately not privileged: it
+ * declares `scopes`/`testedOn` and goes through the same registry and the same
+ * version gate as a third-party provider. Its menu half is registered in the
+ * browser (see `client/git-provider.ts`) because the candidates must be filtered
+ * per keystroke while the repository lives on the Host.
+ */
+export declare const GIT_RESOLVE_PROVIDER: AtlasProvider;

package/lib/types/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * dsh-atlas host plugin: mounts the `atFile` and `atMention` Typert
+ * Remote services (workspace search + category pickers), registers their
+ * strict Typert manifests and the settings namespace, mounts the official
+ * cross-session snapshot service when the profile has not, and marks every
+ * @ mention category (path, skill, past chat, plugin) at each agent's
+ * pre-step boundary. The plugin never reads mentioned file contents. The
+ * client half ships in the same package (`./client`); the web server serves
+ * it under /plugins/dsh-atlas/client.js.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import z from '@deepseek-ai/schemastery';
+import { type ReferenceExpansion } from './mention.ts';
+import type { AtFileSettings, SkillTier } from './contract.ts';
+import type { ResolvedConfig } from './types.ts';
+/** Cordis plugin name (the Loader entry and client bundle id). */
+export declare const name = "dsh-atlas";
+/** Services required before load: the Typert registry, the settings provider, and the agent registry. */
+export declare const inject: string[];
+export { DEFAULT_IGNORE_DIRS, DEFAULT_IGNORE_FILES } from './defaults.ts';
+/**
+ * The public `@` seam surface, for a plugin that wants to register a source.
+ *
+ * `ctx.get('atlas')` is the handle; `AtlasSeam` is the shape to cast it to. A
+ * provider's declaration uses `AtlasProvider`/`AtlasItem`, and both halves type
+ * against the same `AtlasCallContext`.
+ */
+export type { AtlasCallContext, AtlasItem, AtlasProvider, AtlasRegistration, AtlasSeam } from './atlas.ts';
+/** Host plugin configuration, validated at load by the Loader. */
+export interface Config {
+    /** Hard cap on indexed files per workspace; the walk stops and reports truncation. */
+    maxIndexedFiles: number;
+    /** Directory basenames the index walk skips entirely. */
+    ignoreDirs: string[];
+    /** When true, a recognized @skill mention also injects the skill body. */
+    injectSkillBody: boolean;
+}
+/**
+ * Configuration schema: deployment-varying bounds stay tunable from
+ * the profile patch. The inferred schema type keeps the callable form accepting
+ * partial input, so `Config({})` yields the defaults (what the Loader does
+ * for Loader compositions).
+ */
+export declare const Config: z<Schemastery.ObjectS<{
+    maxIndexedFiles: z<number, number>;
+    ignoreDirs: z<string[], string[]>;
+    injectSkillBody: z<boolean, boolean>;
+}>, Schemastery.ObjectT<{
+    maxIndexedFiles: z<number, number>;
+    ignoreDirs: z<string[], string[]>;
+    injectSkillBody: z<boolean, boolean>;
+}>>;
+/** Providers whose bundled skills are system skills (same set as the sidebar Skill Manager). */
+export declare const SYSTEM_BUNDLED_PROVIDERS: Set<string>;
+/**
+ * Map a skill registry source (and its owning provider) onto the management
+ * tiers shown by the sidebar Skill Manager: system / user / project / custom /
+ * plugin. Bundled skills from the filesystem/badge providers are system;
+ * bundled skills from any other provider come from a plugin's own tree.
+ */
+export declare function skillTier(source: string | undefined, provider: string | undefined): SkillTier;
+/**
+ * Build the settings-gated category expansions for one agent. Pure wiring:
+ * the expansion behavior lives in src/references.ts (unit-tested).
+ * @param ctx - the plugin context (service access).
+ * @param agent - the addressed live agent.
+ * @param resolved - resolved plugin configuration.
+ * @param readSettings - live settings read.
+ */
+export declare function buildReferenceExpansion(ctx: Context, agent: {
+    readonly id: unknown;
+} & {
+    readonly session: {
+        readonly id: SessionId;
+        readonly header: {
+            readonly cwd?: string;
+        };
+    };
+}, resolved: ResolvedConfig & {
+    injectSkillBody: boolean;
+}, readSettings: () => AtFileSettings): ReferenceExpansion;
+/**
+ * Mount the atFile/atMention services and the pre-step reference markers.
+ * @param ctx - host cordis context.
+ * @param config - validated plugin configuration (schema defaults applied).
+ */
+export declare function apply(ctx: Context, config?: Config): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `@sidequest-007/dsh-atlas`.
+ * @module @sidequest-007/dsh-atlas/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "dsh-atlas-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>;

package/lib/types/mention.d.ts

@@ -0,0 +1,80 @@
+import type { UserMessage } from '@deepseek-ai/dsh-llm';
+import type { PreStepDecision } from '@deepseek-ai/dsh-agent';
+import { type LineRange } from './tokens.ts';
+import { type ExternalAccess } from './external.ts';
+/** One recognized mention: its workspace-relative token and resolved kind. */
+export interface Mention {
+    /** Workspace-relative path (no leading @, no trailing slash, no line range). */
+    readonly relative: string;
+    readonly kind: 'file' | 'dir';
+    /** Inclusive 1-based line range, present only for `path:start-end` tokens. */
+    readonly lines?: LineRange;
+    /** True when `relative` is an absolute path outside the session workspace. */
+    readonly outside?: true;
+}
+/** The source tag the injected reference carries (transcript consumers use it). */
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'at-file-mention': {
+            kind: 'at-file-mention';
+            relative: string;
+            lines?: string;
+        };
+    }
+}
+/**
+ * Scan one text block for `@path` tokens, deduplicated in first-seen order.
+ * A trailing slash (the directory chip form) is stripped from the path.
+ * @param text - the message text block.
+ * @returns unique workspace-relative tokens.
+ */
+export declare function scanMentions(text: string, ignorePastedMentions?: boolean): readonly string[];
+/**
+ * Expand every `@path` mention into a validated existence-only reference, in
+ * first-seen order. Unknown paths stay plain prose.
+ * @param messages - the assembled step messages.
+ * @param cwd - the session's workspace directory.
+ * @param signal - caller lifetime.
+ * @param ignorePastedMentions - live pasted-@ policy.
+ * @param access - the session's out-of-workspace access, or undefined to refuse external paths.
+ * @param onExternal - called with each accepted external reference, for the ledger.
+ * @returns the injected user messages (empty when nothing matched or disabled).
+ */
+export declare function expandMentions(messages: readonly UserMessage[], cwd: string | undefined, signal: AbortSignal, ignorePastedMentions?: boolean, access?: ExternalAccess, onExternal?: (mention: Mention) => void): Promise<UserMessage[]>;
+/** The minimal agent face the pre-step handler reads. */
+export interface MentionAgent {
+    session: {
+        header: {
+            cwd?: string;
+        };
+    };
+}
+/** The `agent/pre-step` listener body: expand mentions in the claimed user
+ * messages and append the injections to the downstream decision. Extracted so
+ * the boundary logic is unit-testable without an assembled agent scope.
+ * @param agent - the addressed agent (its session header owns the cwd).
+ * @param isEnabled - live settings read.
+ * @param messages - the claimed messages (the user's own words).
+ * @param signal - caller lifetime.
+ * @param next - the downstream waterfall.
+ * @param ignorePastedMentions - live pasted-@ policy.
+ * @param references - optional category expansions (chats, skills, plugins).
+ * @param access - the session's out-of-workspace access, or undefined to refuse external paths.
+ * @param onExternal - called with each accepted external reference, for the ledger.
+ * @returns the decision with injections appended, or the downstream decision.
+ */
+export declare function mentionPreStep(agent: MentionAgent, isEnabled: () => boolean, messages: readonly UserMessage[], signal: AbortSignal, next: () => Promise<PreStepDecision>, ignorePastedMentions?: () => boolean, references?: ReferenceExpansion, access?: ExternalAccess, onExternal?: (mention: Mention) => void): Promise<PreStepDecision>;
+/** Live category expansions wired by the host entry; each is settings-gated. */
+export interface ReferenceExpansion {
+    /** Aggregate past-chat snapshot context, or undefined when none/disabled. */
+    expandChats(messages: readonly UserMessage[], signal: AbortSignal): Promise<UserMessage | undefined>;
+    /** `<skill-reference>` markers for recognized `@skill:` tokens. */
+    expandSkills(messages: readonly UserMessage[], signal: AbortSignal): Promise<readonly UserMessage[]>;
+    /** `<plugin-reference>` markers for recognized `@plugin:` tokens. */
+    expandPlugins(messages: readonly UserMessage[], signal: AbortSignal): Promise<readonly UserMessage[]>;
+    /**
+     * `<atlas-reference>` blocks for recognized `@atlas:<provider>/<item>` tokens,
+     * carrying the body the provider's own `resolve` returned.
+     */
+    expandAtlas?(messages: readonly UserMessage[], signal: AbortSignal): Promise<readonly UserMessage[]>;
+}

package/lib/types/paste.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Internal marker used to distinguish pasted @ tokens from text the user
+ * typed. It is removed at the Host boundary before the prompt reaches the
+ * model. Word joiner has no visible glyph and keeps the displayed draft
+ * unchanged while making the token unambiguous to the plugin.
+ */
+export declare const PASTED_MENTION_MARKER = "\u2060";
+/** Add the internal marker after every @ that starts a pasted token. */
+export declare function protectPastedMentions(text: string): string;
+/** Whether a parsed token contains the internal pasted-text marker. */
+export declare function isProtectedMentionToken(token: string): boolean;
+/** Restore pasted text before it is shown to the model or another consumer. */
+export declare function stripPastedMentionMarkers(text: string): string;

package/lib/types/reference.d.ts

@@ -0,0 +1,16 @@
+import type { ReferenceInfo } from './contract.ts';
+import { type ExternalAccess } from './external.ts';
+/**
+ * Inspect reference paths: workspace-relative ones, plus the absolute
+ * out-of-workspace ones this session is allowed to reference.
+ *
+ * Paths that escape the workspace, are external without access, or do not exist
+ * come back with `exists: false` rather than being dropped, so the dock can
+ * attribute the failure to the exact token the user typed.
+ * @param cwd - the session workspace root (absolute).
+ * @param targets - paths as typed, already stripped of line ranges.
+ * @param signal - caller lifetime.
+ * @param access - the session's out-of-workspace access, or undefined to refuse external paths.
+ * @returns one row per target, in request order.
+ */
+export declare function inspectReferences(cwd: string, targets: readonly string[], signal: AbortSignal, access?: ExternalAccess): Promise<readonly ReferenceInfo[]>;

package/lib/types/references.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Host-side expansion for the non-path @ mention categories: past chats
+ * (official `dsh-session:` snapshot references), skills (`@skill:name`),
+ * and plugins (`@plugin:name`). Each expansion validates the token against a
+ * live capability (session reference resolver, skill registry, plugin
+ * inventory) and injects a sourced user message — never raw content bytes
+ * from the Host side unless the skill body injection config is enabled.
+ * Chat mentions are stripped to readable `@label` text in the user's own
+ * message, and the official `prepare()` snapshot is appended as a separate,
+ * replayable context message.
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ContentBlock, UserMessage } from '@deepseek-ai/dsh-llm';
+import type { AtlasCallContext, AtlasRegistration } from './atlas.ts';
+import { type SessionReferenceInput } from '@deepseek-ai/dsh-session-reference';
+/** The `@skill:name` mention token: `@skill:` then a whitespace/@-free name. */
+export declare const SKILL_MENTION_PATTERN: RegExp;
+/** The `@plugin:name` mention token: `@plugin:` then a whitespace/@-free module name. */
+export declare const PLUGIN_MENTION_PATTERN: RegExp;
+/** The source tag skill reference messages carry (transcript consumers use it). */
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'atlas-skill': {
+            kind: 'atlas-skill';
+            name: string;
+        };
+        'atlas-plugin': {
+            kind: 'atlas-plugin';
+            moduleName: string;
+        };
+        'atlas-provider': {
+            kind: 'atlas-provider';
+            provider: string;
+            item: string;
+        };
+    }
+}
+/** Escape one value for an XML-like reference attribute without altering it. */
+export declare function escapeReferenceAttribute(value: string): string;
+/** The session-reference resolver face this boundary needs (unit-test stub). */
+export interface ChatResolver {
+    prepare(agent: Agent, content: readonly ContentBlock[], references: readonly SessionReferenceInput[], signal: AbortSignal): Promise<{
+        readonly additionalContext?: UserMessage;
+    }>;
+}
+/**
+ * Scan the claimed user messages for `@skill:name` tokens in first-seen
+ * order. Known skills get a `<skill-reference>` marker; when `loadBody` is
+ * provided (config `injectSkillBody`) the skill body is appended in a
+ * `<skill-body>` block so the model can act on the full instructions.
+ * Unknown names stay plain prose.
+ * @param messages - the claimed user messages.
+ * @param isKnown - live lookup: is this skill currently discoverable?
+ * @param signal - caller lifetime.
+ * @param loadBody - optional full-body loader (skill registry `get`).
+ * @returns the injected user messages.
+ */
+export declare function expandSkillMentions(messages: readonly UserMessage[], isKnown: (name: string) => boolean | Promise<boolean>, signal: AbortSignal, loadBody?: (name: string) => Promise<string | undefined>): Promise<UserMessage[]>;
+/**
+ * Scan the claimed user messages for `@plugin:name` tokens in first-seen
+ * order. Enabled plugin modules get a `<plugin-reference>` marker; unknown
+ * or disabled modules stay plain prose.
+ * @param messages - the claimed user messages.
+ * @param isEnabled - live lookup: is this module an enabled plugin?
+ * @param signal - caller lifetime.
+ * @returns the injected user messages.
+ */
+export declare function expandPluginMentions(messages: readonly UserMessage[], isEnabled: (moduleName: string) => boolean | Promise<boolean>, signal: AbortSignal): Promise<UserMessage[]>;
+/** The `@atlas:<provider>/<item>` token: a provider handle, then its own item id. */
+export declare const ATLAS_MENTION_PATTERN: RegExp;
+/** How much one provider body may add to a single step. */
+export declare const ATLAS_BODY_LIMIT = 16384;
+/** How much every provider body may add to a single step in total. */
+export declare const ATLAS_TOTAL_LIMIT = 49152;
+/** One `@atlas:` mention, split into the handle and the provider's own item id. */
+export interface AtlasMentionTarget {
+    readonly providerId: string;
+    readonly item: string;
+}
+/**
+ * Scan the claimed user messages for `@atlas:<provider>/<item>` tokens and inject
+ * one reference per token, carrying the body the provider's own `resolve` returns.
+ *
+ * ATLAS never reads a provider's data: the body arrives through the provider's
+ * callback, is bounded here, and is never persisted — the usage counter records
+ * only the `provider/item` handle. A provider that is not registered, or whose
+ * `resolve` fails, contributes nothing rather than blocking the send.
+ * @param messages - the claimed user messages.
+ * @param context - the answered session, its workspace, and caller lifetime,
+ *   handed to the provider verbatim.
+ * @param lookup - the live injection-side registrations.
+ * @returns the injected user messages, in first-seen order.
+ */
+export declare function expandAtlasMentions(messages: readonly UserMessage[], context: AtlasCallContext, lookup: (providerId: string) => AtlasRegistration | undefined): Promise<readonly UserMessage[]>;
+/**
+ * Extract `dsh-session:` references from the claimed user messages in
+ * first-mention order and return the messages with the markdown mentions
+ * normalized to readable `@label` text.
+ * @param messages - the claimed user messages.
+ * @returns structured references plus the cleaned message copy.
+ */
+export declare function collectChatReferences(messages: readonly UserMessage[]): {
+    readonly references: readonly SessionReferenceInput[];
+    readonly cleaned: readonly UserMessage[];
+};
+/**
+ * Normalize `dsh-session:` markdown mentions in the user messages to
+ * readable `@label` text without preparing any context. Applied by the
+ * pre-step wrapper whenever chat references are enabled so the raw URI never
+ * reaches the model; unknown labels stay as parsed.
+ * @param messages - the assembled step messages.
+ * @returns the cleaned message copy.
+ */
+export declare function cleanChatMentions(messages: readonly UserMessage[]): readonly UserMessage[];
+/**
+ * Prepare one aggregated past-chat snapshot for the claimed user messages.
+ * Returns the official `additionalContext` user message, or undefined when
+ * the claim has no `dsh-session:` references or the resolver produced none.
+ * Errors are surfaced to the caller (the pre-step wrapper logs and continues).
+ * @param agent - the live agent whose session is the reference target.
+ * @param resolver - `ctx.sessionReferenceResolver` (official service).
+ * @param messages - the claimed user messages.
+ * @param signal - caller lifetime.
+ * @returns the context message to place before the user's own words.
+ */
+export declare function expandChatMentions(agent: Agent, resolver: ChatResolver, messages: readonly UserMessage[], signal: AbortSignal): Promise<UserMessage | undefined>;

package/lib/types/runtime-info.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The anchors to try, in order, when locating the running Harness manifest.
+ *
+ * `entry` — the process's own entry point — is the Harness that is actually up,
+ * and it is the only anchor whose answer can be trusted when the plugin's own
+ * module graph reaches a *different* Harness build. That is the normal shape of
+ * a linked development install: the profile loads the plugin from the checkout
+ * while the running CLI comes from the global install, so a plugin-anchored
+ * lookup resolves the checkout (or nothing at all) and every `testedOn` claim
+ * would be judged against the wrong version. `self` stays as the fallback for
+ * launches where the entry point is a loader rather than the Harness.
+ * @param entry - `process.argv[1]`, or undefined when the process has none.
+ * @param self - this module's own URL.
+ * @returns the anchors, most trustworthy first.
+ */
+export declare function versionAnchors(entry: string | undefined, self: string): readonly string[];
+/**
+ * Read the first anchor that yields a manifest, or rethrow the last failure.
+ * @param anchors - candidate anchors, most trustworthy first.
+ * @param read - how to read the manifest at one anchor.
+ * @returns the manifest text from the first anchor that had one.
+ */
+export declare function readFirstAvailable(anchors: readonly string[], read: (anchor: string) => string): string;
+/**
+ * Read the installed DSH version.
+ * @param resolvePackageJson - how to locate the package manifest; injectable so
+ *   the failure paths are testable without a broken install.
+ * @returns the version string, or undefined when it cannot be established.
+ */
+export declare function readDshVersion(resolvePackageJson?: () => string): string | undefined;