@adaptiqai/deepseek-harness 0.2.5 → 0.2.11

package/lib/types/client/attach.d.ts

@@ -0,0 +1,105 @@
+/** What the memory pill's "Add" list shows and the pill's "+ added" moment, kept apart from React so they can be tested. */
+import type { ConversationItem, KnowledgeItem, SessionView } from '@adaptiqai/core/types';
+type T = (key: string, params?: Record<string, unknown>) => string;
+/** One row of the pill's add list: a conversation or a collection, on or off. */
+export interface AttachRow {
+    readonly id: string;
+    readonly kind: 'conversation' | 'collection';
+    readonly name: string;
+    readonly updatedAt: number | null;
+    readonly tokens: number | null;
+    /** Attached to this conversation. */
+    readonly on: boolean;
+    /** Readiness of an attached item; a collection not ready yet cannot be added. `deferred`: used from the first message. */
+    readonly status: 'ready' | 'preparing' | 'failed' | 'not-ready' | 'deferred';
+}
+/** A collection in the add list's Knowledge tab. */
+export interface KnowledgeRow extends AttachRow {
+    readonly kind: 'collection';
+    /** Made in the last {@link NEW_MS}: marked new. */
+    readonly isNew: boolean;
+    /** The model it is made for, when it is not this conversation's. */
+    readonly model: string | null;
+    /** Made for another model: greyed, with "make available" when the server can. */
+    readonly other: boolean;
+    readonly convertible: boolean;
+    readonly copying: 'building' | 'failed' | null;
+}
+/** How long a collection counts as new. */
+export declare const NEW_MS: number;
+/**
+ * The add list's Knowledge tab: the collections that work here, newest first
+ * (the ones made in the last days marked new), then the ones made for another
+ * model, greyed. Search only filters.
+ * @param view - the conversation.
+ * @param collections - the library page, or null while loading.
+ * @param query - search text.
+ * @param now - the time, for "new".
+ * @returns usable and other rows.
+ */
+export declare function knowledgeRows(view: SessionView, collections: readonly KnowledgeItem[] | null, query: string, now: number): {
+    usable: KnowledgeRow[];
+    other: KnowledgeRow[];
+};
+/**
+ * The add list's Conversations tab: recent conversations on this model, newest
+ * first as the server pages them, never this one.
+ * @param view - the conversation.
+ * @param conversations - conversations on its model, or null while loading.
+ * @param query - search text.
+ * @returns the rows.
+ */
+export declare function conversationRows(view: SessionView, conversations: readonly ConversationItem[] | null, query: string): AttachRow[];
+/** One chip above the message box: something this conversation uses. */
+export interface Chip {
+    readonly id: string;
+    readonly kind: 'collection' | 'conversation';
+    readonly name: string;
+    /** `preparing` shows a quiet progress; `failed` a muted mark. */
+    readonly state: 'ready' | 'preparing' | 'deferred' | 'failed';
+}
+/**
+ * The chips above the message box: the collections and conversations this
+ * conversation uses, and the collections made for it that are still getting ready.
+ * @param view - the conversation.
+ * @returns the chips, collections first.
+ */
+export declare function chipItems(view: SessionView): Chip[];
+/** How long the pill says what a mention just added. */
+export declare const ADDED_MS = 5000;
+/**
+ * The pill's words after a mention or a new collection: what was added, what
+ * stays text because it is on another model, and a collection that just became
+ * ready and is used here.
+ * @param t - translate.
+ * @param added - the conversation's "just added" mark.
+ * @returns e.g. "+ Novel A, Novel B" or "“The book” ready, used here".
+ */
+export declare function addedText(t: T, added: {
+    readonly names: readonly string[];
+    readonly otherModel: readonly string[];
+    readonly ready?: readonly string[];
+}): string;
+/**
+ * Follows a conversation's "just added" mark and reports a new one for
+ * {@link ADDED_MS}. A mark already there when the view first arrives is history.
+ */
+export declare class AddedFlash {
+    private readonly onChange;
+    private readonly ms;
+    private baseline;
+    private timer;
+    constructor(onChange: (added: NonNullable<SessionView['added']> | null) => void, ms?: number);
+    seen(added: SessionView['added'] | undefined): void;
+    dispose(): void;
+}
+/**
+ * The pill's words while a collection created for this conversation is prepared.
+ * @param t - translate.
+ * @param preparing - the collections still preparing.
+ * @returns e.g. "Preparing “The book”…"; with several, the first and how many more.
+ */
+export declare function preparingText(t: T, preparing: readonly {
+    readonly name: string;
+}[]): string;
+export {};

package/lib/types/client/store.d.ts

@@ -47,6 +47,8 @@ export interface AdaptiqRemote {
     refresh(): Promise<RemoteResult<AccountSnapshot>>;
     setPreferences(patch: Partial<Preferences>): Promise<RemoteResult<Preferences>>;
     dismissNotice(id: string): Promise<RemoteResult<void>>;
+    updatePlugin(): Promise<RemoteResult<void>>;
+    activateUpdate(): Promise<RemoteResult<void>>;
     getSession(sessionId: string): Promise<RemoteResult<SessionView>>;
     watchSession(sessionId: string, signal?: AbortSignal): AsyncIterable<SessionView> & {
         dispose(): void;

package/lib/types/host/adapter.d.ts

@@ -6,7 +6,8 @@
  */
 import { LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm';
 import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, PreparedAdapterCall, ResolvedRetryPolicy, StreamChunk } from '@deepseek-ai/dsh-llm';
-import { type AdaptiqFailure, type AuthManager, type CatalogModel, type RequestEvents } from '@adaptiqai/core';
+import { type AdaptiqFailure, type AuthManager, type CatalogModel, type RequestEvents, type UserTurn } from '@adaptiqai/core';
+import { type ParentSession, type ReferencedSession } from './wire.ts';
 /** What the adapter tells the rest of the plugin about each request. */
 export interface AdapterDeps {
     readonly route: string;
@@ -26,9 +27,33 @@ export interface AdapterDeps {
     remember(sessionId: string | undefined): boolean;
     /** Whether the server already stores this conversation (may look it up first). */
     stored(sessionId: string | undefined): boolean | Promise<boolean>;
+    /**
+     * Attach the sessions a message mentioned with `@` to this conversation, when
+     * they are AdaptiqAI conversations on the same model.
+     * @returns session id → name of those attached and ready to read from memory.
+     */
+    recall?(sessionId: string, model: string, references: readonly ReferencedSession[], signal: AbortSignal): Promise<ReadonlyMap<string, string>>;
+    /** Attach what was added to the conversation before this, its first, message. */
+    attachPending?(sessionId: string): Promise<void>;
+    /** What the person wrote in this conversation (their own messages, marked when they answer an offer to save knowledge), for the tools' guards. */
+    noteUserTexts?(sessionId: string, texts: readonly UserTurn[]): void;
+    /** The session that started this one (a subagent's or teammate's parent), if any. */
+    parentSession?(sessionId: string): ParentSession | undefined;
     readonly events: RequestEvents;
+    /** Whether the server behind a model puts idle conversations to sleep (it reports session history apart). */
+    readonly autoSleep?: (model: string) => boolean;
+    /** Diagnostics for one request (no content), when a debug log is on. */
+    debug?(message: string): void;
     readonly fetch?: typeof fetch;
 }
+/** How long a first message waits for what was added before it to attach. */
+export declare const ATTACH_WAIT_MS = 10000;
+/**
+ * How often a conversation is told that it needs no compacting. The harness asks
+ * again at every step once its history passes its pressure threshold; the
+ * answer is the same each time and one toast says it.
+ */
+export declare const COMPACTION_NOTICE_MS: number;
 /** The harness retries busy and preparing answers itself, honouring Retry-After. */
 export declare const RETRY_POLICY: ResolvedRetryPolicy;
 /**
@@ -42,8 +67,11 @@ export declare function resolvedInfo(route: string, model: CatalogModel): LlmRes
 export declare function toLlmError(failure: AdaptiqFailure, cause?: unknown): LlmError;
 export declare class AdaptiqAdapter extends LlmAdapter {
     private readonly deps;
+    private readonly now;
     private readonly fetch;
-    constructor(deps: AdapterDeps);
+    /** When each conversation was last told that nothing needs compacting. */
+    private readonly compactionTold;
+    constructor(deps: AdapterDeps, now?: () => number);
     providerInfo(provider: string): LlmProviderInfo;
     providerRetryPolicy(): ResolvedRetryPolicy;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;

package/lib/types/host/commands.d.ts

@@ -1,6 +1,9 @@
 /** `/adaptiq`: status, sign-in, privacy and knowledge from the composer, in plain text. */
 import type { Context } from '@deepseek-ai/cordis';
 import { type AuthManager, type Workspace } from '@adaptiqai/core';
+export declare const HELP: string;
+/** The actions the composer offers after `/adaptiq`: every one HELP lists. */
+export declare const HINT = "status \u00B7 signin \u00B7 private \u00B7 remember \u00B7 knowledge \u00B7 open \u00B7 diagnostics \u00B7 signout";
 /**
  * The action word of `/adaptiq …`, however the composer passes it: with or
  * without the command name, a leading slash, or a completion glued on with "/".

package/lib/types/host/controller.d.ts

@@ -30,6 +30,8 @@ export declare class AdaptiqController extends TypertRemoteService {
     private readonly deps;
     static inject: string[];
     constructor(ctx: Context, deps: ControllerDeps);
+    /** A stream ends when its caller leaves or this plugin code is replaced (an update loaded in place). */
+    private until;
     /** Read the current account snapshot. */
     getState(): Promise<AccountSnapshot>;
     /** Follow the account snapshot: the current one, then every change. */
@@ -46,6 +48,10 @@ export declare class AdaptiqController extends TypertRemoteService {
     setPreferences(patch: Partial<Preferences>): Promise<Preferences>;
     /** Take one notice down. */
     dismissNotice(id: string): Promise<void>;
+    /** Install the newest published version through the harness and load it, without a restart where the harness allows. */
+    updatePlugin(): Promise<void>;
+    /** Switch to the newer version already installed on disk. */
+    activateUpdate(): Promise<void>;
     /** Read one conversation's memory and knowledge. */
     getSession(sessionIdValue: string): Promise<SessionView>;
     /** Follow one conversation's memory and request state. */

package/lib/types/host/entry.d.ts

@@ -0,0 +1,29 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.ts';
+import type { HostRuntime } from './updater.ts';
+export { Config };
+export declare const name = "adaptiq";
+export declare const inject: string[];
+export declare const usage = "\nAdaptiqAI models with native memory, signed in with your AdaptiqAI account.\nOpen **Settings \u2192 AdaptiqAI** to connect, or run `/adaptiq signin`.\n";
+/** What this loader offers the code it loads; bumped when that changes. */
+export declare const ENTRY_PROTOCOL = 1;
+/** What lib/host.js exports. */
+export interface HostModule {
+    applyWith(ctx: Context, config: Config, runtime: HostRuntime | undefined): Promise<void>;
+    /** Remote methods, composition and configuration schema: equal means the new code can replace the old in place. */
+    readonly RELOAD_SIGNATURE: string;
+    readonly ENTRY_PROTOCOL: number;
+    readonly VERSION: string;
+}
+/** Where the Host half and the package manifest live, beside this file. */
+export interface HostFiles {
+    readonly host: URL;
+    readonly manifest: URL;
+}
+/**
+ * Mount the plugin through the swappable Host half.
+ * @param ctx - the plugin context.
+ * @param config - resolved configuration.
+ * @param files - where the code lives (tests point elsewhere).
+ */
+export declare function apply(ctx: Context, config: Config, files?: HostFiles): Promise<void>;

package/lib/types/host/index.d.ts

@@ -1,12 +1,26 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { Config } from './config.ts';
+import { type HostRuntime } from './updater.ts';
 export { Config };
 export declare const name = "adaptiq";
 export declare const inject: string[];
 export declare const usage = "\nAdaptiqAI models with native memory, signed in with your AdaptiqAI account.\nOpen **Settings \u2192 AdaptiqAI** to connect, or run `/adaptiq signin`.\n";
+/** The loader protocol this code expects (entry.ts ENTRY_PROTOCOL). */
+export declare const ENTRY_PROTOCOL = 1;
+/** Remote methods, composition and configuration schema, fixed at build time. */
+export declare const RELOAD_SIGNATURE: string;
+/** The version of this code. */
+export declare const VERSION: string;
 /**
- * Mount the plugin.
+ * Mount the plugin, loaded directly.
  * @param ctx - the plugin context.
  * @param config - resolved configuration.
  */
 export declare function apply(ctx: Context, config: Config): Promise<void>;
+/**
+ * Mount the plugin.
+ * @param ctx - the plugin context.
+ * @param raw - configuration, resolved again with this version's own defaults.
+ * @param runtime - the loader's update hooks, when lib/index.js loaded this code.
+ */
+export declare function applyWith(ctx: Context, raw: Config, runtime: HostRuntime | undefined): Promise<void>;

package/lib/types/host/relations.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Where a live harness session came from: its subagents are helpers of the
+ * session that started them, its Agent Team's teammates are tracks. Read from
+ * the harness's own services, all optional.
+ */
+import { type ParentSession, type SessionOrigin } from './wire.ts';
+/** A live harness Agent, as `agents` returns it. */
+export interface AgentLike {
+    readonly session?: {
+        readonly header?: SessionOrigin;
+    };
+}
+/** The harness context, as far as this reads it. */
+export interface ServicesLike {
+    get(name: string): unknown;
+}
+/**
+ * The session that started a live harness session.
+ * @param ctx - the plugin context.
+ * @param sessionId - harness session id.
+ * @returns the parent and role, or undefined for a root session or one not loaded.
+ */
+export declare function sessionParent(ctx: ServicesLike, sessionId: string): ParentSession | undefined;

package/lib/types/host/stream.d.ts

@@ -4,12 +4,14 @@
  * finish, nothing after finish.
  */
 import type { StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm';
-import { type SseEvent } from '@adaptiqai/core';
+import { type MemoryNotice, type SseEvent } from '@adaptiqai/core';
 export { mapUsage, parseSse, type SseEvent } from '@adaptiqai/core';
 /** Hooks the translator calls as the stream unfolds. */
 export interface TranslateHooks {
     /** A server progress frame (`adaptiq.progress`): stage such as `context.preparing` or `inference.queued`. */
     onProgress?(stage: string, elapsedMs: number | null): void;
+    /** The engine put idle conversations to sleep, or suggests which may (`adaptiq.memory`). */
+    onMemoryNotice?(notice: MemoryNotice): void;
     /** The first visible output (text, thinking or a tool call) arrived. */
     onFirstOutput?(): void;
     /** An in-band error: map it to the thrown failure. */

package/lib/types/host/tools.d.ts

@@ -1,5 +1,5 @@
 import type { Context } from '@deepseek-ai/cordis';
-import type { Workspace } from '@adaptiqai/core';
+import { type Workspace } from '@adaptiqai/core';
 /**
  * The media type for a file name.
  * @param name - file name.

package/lib/types/host/updater.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Updating the plugin from inside the harness: the profile's plugin manager
+ * (`pluginManager`, the service behind the Plugins page) installs the
+ * version, and the loader in lib/index.js swaps the running Host half for the
+ * new code (see entry.ts).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type PluginUpdater, UpdateFailure } from '@adaptiqai/core';
+/** What lib/index.js offers the code it loads; absent when this module was loaded directly. */
+export interface HostRuntime {
+    /** The version in the package.json on disk now, or null when it cannot be read. */
+    installedVersion(): string | null;
+    /** Whether the code on disk can replace the running code in place (same Remote methods and composition). */
+    canReload(): Promise<boolean>;
+    /** Replace the running Host half with the code on disk, right after this call returns. */
+    reload(): Promise<'reloaded' | 'restart'>;
+}
+interface ChangeResultLike {
+    application: 'applied' | 'restart-required' | 'overridden' | 'failed' | 'cancelled';
+    error?: {
+        code: string;
+        diagnostic?: string;
+    };
+    packageResult?: {
+        kind?: string;
+        output?: string;
+    };
+}
+/**
+ * Why an install did not finish, in the words the person is told.
+ * @param result - the plugin manager's outcome.
+ * @returns the failure.
+ */
+export declare function installFailure(result: ChangeResultLike): UpdateFailure;
+/**
+ * The updater for this harness.
+ * @param ctx - the plugin context.
+ * @param name - the plugin's package name.
+ * @param runtime - the loader's reload hooks, when lib/index.js loaded this code.
+ * @returns the updater the Workspace drives.
+ */
+export declare function harnessUpdater(ctx: Context, name: string, runtime: HostRuntime | undefined): PluginUpdater;
+export {};

package/lib/types/host/wire.d.ts

@@ -3,8 +3,8 @@
  * (thinking field and values, sampling defaults) comes only from the
  * model's catalog entry.
  */
-import type { GenerateOptions } from '@deepseek-ai/dsh-llm';
-import { type CatalogModel } from '@adaptiqai/core';
+import type { GenerateOptions, RequestMessage } from '@deepseek-ai/dsh-llm';
+import { type CatalogModel, type SessionRole, type UserTurn } from '@adaptiqai/core';
 /** One Chat Completions message. */
 export type WireMessage = {
     role: 'system';
@@ -38,13 +38,65 @@ export interface WireExtras {
     readonly stored?: boolean;
     /** Ask for streamed usage (always on for the adapter). */
     readonly includeUsage?: boolean;
+    /** Referenced sessions attached to this conversation and ready, by session id → name. */
+    readonly recalled?: ReadonlyMap<string, string>;
 }
+/** One session another message mentioned with `@`, as the harness snapshot records it. */
+export interface ReferencedSession {
+    readonly sessionId: string;
+    readonly label: string;
+}
+/**
+ * The sessions a harness `## Referenced sessions` snapshot carries, read from
+ * the message's structured source (`kind: 'session-reference'`), never its text.
+ * @param message - one request message.
+ * @returns the referenced sessions, or null when the message is not a snapshot.
+ */
+export declare function sessionReferences(message: RequestMessage): ReferencedSession[] | null;
+/**
+ * Every session the request's history mentions, first mention first.
+ * @param messages - the request history.
+ * @returns unique referenced sessions.
+ */
+export declare function referencedSessions(messages: readonly RequestMessage[]): ReferencedSession[];
+/**
+ * The line that stands in for transcripts the conversation now reads from memory.
+ * @param names - the attached conversations' names.
+ * @returns one short line for the model.
+ */
+export declare function recallLine(names: readonly string[]): string;
+/**
+ * A snapshot with the sessions read from memory taken out: one line names them,
+ * and the transcripts of any other referenced sessions stay as the harness wrote them.
+ * When the snapshot cannot be split safely it is kept whole.
+ * @param text - the snapshot text.
+ * @param references - the sessions it carries.
+ * @param recalled - session id → name of the sessions attached and ready.
+ * @returns the text to send.
+ */
+export declare function recallSnapshot(text: string, references: readonly ReferencedSession[], recalled: ReadonlyMap<string, string>): string;
+/**
+ * What the person wrote in the request history: their own messages (typed, or
+ * answered to a question of the model) only, not the harness's snapshots,
+ * runtime context or tool output.
+ * @param messages - the request history.
+ * @returns the text of each of the person's messages, oldest first.
+ */
+export declare function userTexts(messages: readonly RequestMessage[]): string[];
+/**
+ * What the person wrote in the request history, each message marked when it
+ * answers the agent's offer to save knowledge (the agent asked right before).
+ * @param messages - the request history.
+ * @returns the person's turns, oldest first.
+ */
+export declare function userTurns(messages: readonly RequestMessage[]): UserTurn[];
 /**
  * Convert the harness history to Chat Completions messages.
  * @param options - the harness request.
+ * @param recalled - referenced sessions read from memory: their snapshots become one line.
  * @returns the wire messages in order.
  */
-export declare function wireMessages(options: Pick<GenerateOptions, 'messages' | 'system'>): WireMessage[];
+export declare function wireMessages(options: Pick<GenerateOptions, 'messages' | 'system'>, recalled?: ReadonlyMap<string, string>): WireMessage[];
 /**
  * Build the request body for one call.
  * @param options - the harness request.
@@ -53,10 +105,32 @@ export declare function wireMessages(options: Pick<GenerateOptions, 'messages' |
  * @returns the JSON body.
  */
 export declare function buildChatBody(options: GenerateOptions, model: CatalogModel | null, extras: WireExtras): Record<string, unknown>;
+/** The session that started a session, and how it relates to it. */
+export interface ParentSession {
+    readonly parentSessionId: string;
+    readonly role: SessionRole;
+}
+/** What a harness session header says about where the session came from. */
+export interface SessionOrigin {
+    readonly parentSession?: string;
+    readonly origin?: string;
+    readonly delegationDepth?: number;
+}
+/**
+ * The parent of a harness session. A subagent (`origin: 'subagent'` or a
+ * delegation depth) works for its parent: `helper`; a member of the parent's
+ * Agent Team is its own line of work: `track`. A root session and a fork the
+ * person made (`parentSession` without delegation) have none.
+ * @param header - the session's header.
+ * @param teammate - whether the Agent Team service counts the session as a teammate.
+ * @returns the parent and role, or undefined.
+ */
+export declare function parentSession(header: SessionOrigin | undefined, teammate: boolean): ParentSession | undefined;
 /**
  * The session headers for one call. A title request carries none: it reuses the
  * conversation id with a different history and must not fork the saved conversation.
  * @param options - the harness request.
+ * @param parent - the session that started this one, if any.
  * @returns header name → value.
  */
-export declare function sessionHeaders(options: Pick<GenerateOptions, 'sessionId' | 'purpose'>): Record<string, string>;
+export declare function sessionHeaders(options: Pick<GenerateOptions, 'sessionId' | 'purpose'>, parent?: ParentSession): Record<string, string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptiqai/deepseek-harness",
-  "version": "0.2.5",
+  "version": "0.2.11",
   "description": "AdaptiqAI for DeepSeek Harness: models with 5M-token native memory and Knowledge. Sign up, get a model and work without leaving the harness",
   "keywords": [
     "dsh-plugin",
@@ -42,6 +42,7 @@
     "cordis.patch.yml",
     "locale/*.json",
     "lib/index.js",
+    "lib/host.js",
     "lib/client.js",
     "lib/typert.host.js",
     "lib/typert.host.d.ts",
@@ -89,7 +90,7 @@
     "react-dom": "~18.3.1",
     "typescript": "~5.9.3",
     "vitest": "~3.2.7",
-    "@adaptiqai/core": "0.2.5"
+    "@adaptiqai/core": "0.2.7"
   },
   "repository": {
     "type": "git",