@adaptiqai/deepseek-harness 0.2.18 → 0.2.20

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

@@ -5,8 +5,8 @@
  * the server keeps one native memory per conversation.
  */
 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, type UserTurn } from '@adaptiqai/core';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, PreparedAdapterCall, RequestMessage, ResolvedRetryPolicy, StreamChunk } from '@deepseek-ai/dsh-llm';
+import { type AdaptiqFailure, type AuthManager, type CatalogModel, PREPARING_GAVE_UP, type PreparingWhat, type RequestEvents, type UserTurn } from '@adaptiqai/core';
 import { type ImageLimits, type ImageRef, type ImageSource } from './images.ts';
 import { type ParentSession, type ReferencedSession } from './wire.ts';
 /** What the adapter tells the rest of the plugin about each request. */
@@ -38,11 +38,22 @@ export interface AdapterDeps {
     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 conversation's whole history, as the harness sent it, for find in it. */
+    noteConversation?(sessionId: string, messages: readonly RequestMessage[]): 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;
+    /** A model's conversation memory when it is full: what is taken and its size. */
+    readonly sessionMemoryFull?: (model: string) => Promise<{
+        readonly usedTokens: number;
+        readonly limitTokens: number;
+    } | null>;
+    /** The collections a conversation uses, for the words while it gets ready. */
+    readonly preparing?: (sessionId: string) => PreparingWhat | null;
+    /** Waits `ms` unless the signal stops it first (tests pass their own). */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     /** The harness's attachment service, where attached images are stored (absent on hosts without one). */
     attachments?(): ImageSource | undefined;
     /** Where the model's tools can read the stored copy of an image. */
@@ -63,8 +74,9 @@ export declare const ATTACH_WAIT_MS = 10000;
  * 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;
+/** The last "getting ready" answer of a turn, in the core's words for every harness. */
+export { PREPARING_GAVE_UP };
 /**
  * Exact-route model info the harness reads (context window, efforts, output default).
  * @param route - provider route id.
@@ -80,7 +92,22 @@ export declare class AdaptiqAdapter extends LlmAdapter {
     private readonly fetch;
     /** When each conversation was last told that nothing needs compacting. */
     private readonly compactionTold;
+    /** Each conversation's "getting ready" answers in a row: how many, for which of the person's messages, and when the last came. */
+    private readonly preparingRun;
+    /** What each conversation's next "getting ready" wait holds past the harness's longest, waited here. */
+    private readonly preparingHold;
     constructor(deps: AdapterDeps, now?: () => number);
+    /**
+     * A conversation's failure, counted in its run of "getting ready" answers
+     * for the same message of the person: the one after the harness's last
+     * retry says that nothing was answered, instead of promising another try.
+     * Any other answer ends the run.
+     * @param sessionId - the conversation.
+     * @param turn - how many messages of the person the request holds, when known.
+     * @param failure - the failure as classified.
+     * @returns the failure, worded for the last try when it is one.
+     */
+    private lastTry;
     providerInfo(provider: string): LlmProviderInfo;
     providerRetryPolicy(): ResolvedRetryPolicy;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;

package/lib/types/host/added-conversations.d.ts

@@ -0,0 +1,106 @@
+import { type knowledgeReading, type ReadingArgs, type Workspace } from '@adaptiqai/core';
+import type { ConversationTexts } from './conversations.ts';
+/** One logged event of a session, as far as a find reads it. */
+interface LoggedEvent {
+    readonly type: string;
+    readonly seq: number;
+    /** Unix epoch milliseconds. */
+    readonly time: number;
+    readonly data?: unknown;
+}
+/** One exact cut of a session: a live one copies its log only when `events` is read. */
+interface Observation {
+    readonly events: readonly LoggedEvent[];
+    /** The last event's seq, or -1 for an empty log. */
+    readonly cursor: number;
+    /** The stored copy's revision, for a session that is not open. */
+    readonly revision?: string;
+    [Symbol.dispose]?(): void;
+}
+/**
+ * The harness's session reads (`sessionQuery`). Newer hosts observe a session's
+ * whole log; older ones read its current surface, where a compacted part is
+ * only its summary (AdaptiqAI's own conversations are never compacted).
+ */
+export interface SessionReads {
+    observeSession?(sessionId: string, options: {
+        readonly projectionMode: 'none';
+        readonly signal?: AbortSignal;
+    }): Promise<Observation>;
+    readSurface?(sessionId: string): Promise<{
+        readonly capturedThroughSeq: number | null;
+        readonly events: readonly LoggedEvent[];
+    }>;
+}
+/** How far a conversation is read: the last event a mention captured, and when it was made private. */
+interface Limits {
+    readonly through: number | undefined;
+    readonly since: number | null;
+}
+/** A conversation's lines, and what of it was left out. */
+interface Read {
+    readonly lines: readonly string[];
+    /** How many of the person's messages the lines hold: the version a next page keeps to. */
+    readonly messages: number;
+    /** Messages written there after the mention captured it. */
+    readonly newer: boolean;
+    /** Messages written there after it was made private. */
+    readonly unsaved: boolean;
+}
+type Outcome = {
+    readonly kind: 'read';
+    readonly read: Read;
+} | {
+    readonly kind: 'missing' | 'failed' | 'unsupported';
+};
+/**
+ * What the person wrote in a session, as lines: each message headed with its
+ * number, its text a line each, an empty line after it. The harness's
+ * injected context, @ snapshots, compaction summaries, the plugin's notes,
+ * the agent's replies, tool calls and results are left out.
+ * @param events - the session's logged events, oldest first.
+ * @param limits - the last event a mention captured, and when it was made private.
+ * @returns the lines, and what was left out past the limits.
+ */
+export declare function addedLines(events: readonly LoggedEvent[], limits: Limits): Read;
+/** The added conversations' lines, read through the harness and kept while they do not change. */
+export declare class AddedConversations {
+    private readonly reads;
+    private readonly kept;
+    private chars;
+    /** @param reads - the harness's session reads, when it has them. */
+    constructor(reads: () => SessionReads | undefined);
+    /**
+     * A conversation's lines, read again only when it changed (its cursor or
+     * revision) or its limits did.
+     * @param sessionId - the conversation.
+     * @param limits - how far it is read.
+     * @param signal - cancellation.
+     * @returns its lines; missing when the harness has no such conversation here, failed when it could not be read, unsupported when this harness reads no conversations.
+     */
+    read(sessionId: string, limits: Limits, signal?: AbortSignal): Promise<Outcome>;
+    /** A kept read of a conversation as it is now, which becomes the most recently used. */
+    private recall;
+    /** Keep a read; the least recently used go past four conversations or 24M characters, never the one just read. */
+    private keep;
+}
+/** What find_in_conversation reads with: the workspace, this conversation's history, the added ones' reads and core's listing. */
+export interface AddedFind {
+    readonly workspace: Workspace;
+    readonly conversations: ConversationTexts | undefined;
+    readonly added: AddedConversations;
+    readonly reader: Pick<ReturnType<typeof knowledgeReading>, 'findInConversations'>;
+}
+/**
+ * Find in a conversation added here, by its name, or in this one and every
+ * added one together ("all"), as one list. What could not be searched is
+ * said under the page's first line.
+ * @param context - what it reads with.
+ * @param sessionId - the conversation the find runs in.
+ * @param which - a conversation's name, or "all".
+ * @param args - the words, and more, fields, sort, sum and group as for find.
+ * @param signal - cancellation.
+ * @returns one page.
+ */
+export declare function findInAdded(context: AddedFind, sessionId: string, which: string, args: ReadingArgs, signal?: AbortSignal): Promise<string>;
+export {};

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

@@ -1,16 +1,12 @@
 /** `/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';
+import { type AuthManager, commandAction, type Workspace } from '@adaptiqai/core';
+/** DeepSeek Harness's own words: its Settings page, its picker and its Knowledge panel. */
+export declare const WORDS: import("@adaptiqai/core").CommandWords;
 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 "/".
- * @param rawInput - text after (or including) the command name.
- * @returns the action, lower case; "" for none.
- */
-export declare function commandAction(rawInput: string): string;
+export declare const HINT: string;
+export { commandAction };
 /**
  * Register `/adaptiq`.
  * @param ctx - context with the `commands` service.

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

@@ -0,0 +1,28 @@
+import type { RequestMessage } from '@deepseek-ai/dsh-llm';
+export declare class ConversationTexts {
+    private readonly held;
+    /**
+     * Keep a conversation's history, as the harness sent it for a request.
+     * @param sessionId - the conversation.
+     * @param messages - its history.
+     */
+    note(sessionId: string, messages: readonly RequestMessage[]): void;
+    /**
+     * A conversation's history, as the harness last sent it.
+     * @param sessionId - the conversation.
+     * @returns its messages, or null when no request of it was seen.
+     */
+    messages(sessionId: string): readonly RequestMessage[] | null;
+    /**
+     * A conversation's messages as lines, and a version that changes when the
+     * person writes again: each step of a turn adds the agent's call and its
+     * result, and a version of all the messages sent every next page back to
+     * the first.
+     * @param sessionId - the conversation.
+     * @returns them, or null when no request of it was seen.
+     */
+    lines(sessionId: string): {
+        readonly lines: readonly string[];
+        readonly version: string;
+    } | null;
+}

package/lib/types/host/knowledge-note.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A turn is told which collections its conversation reads, once and again
+ * when they change. Nothing else in a turn says a collection is in use, so an
+ * agent asked about an id in one searched the person's files instead.
+ *
+ * The note is a sourced user message the agent loop logs with the turn's
+ * first step, as the harness's own context producers add theirs: the model
+ * reads it in every later request, and the conversation view shows it as
+ * context, not as the person's words.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ContextFormed, type UserMessage } from '@deepseek-ai/dsh-llm';
+import { type TurnNotes, type Workspace } from '@adaptiqai/core';
+/** Who produced the note, in the message's source. */
+export declare const NOTE_KIND = "adaptiq-knowledge";
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'adaptiq-knowledge': {
+            kind: 'adaptiq-knowledge';
+        } & ContextFormed;
+    }
+}
+/** One logged event of a session, as far as the note reads it. */
+interface LoggedEvent {
+    readonly type?: string;
+    readonly data?: {
+        readonly source?: {
+            readonly kind?: unknown;
+        };
+        readonly content?: readonly {
+            readonly type?: string;
+            readonly text?: unknown;
+        }[];
+    };
+}
+/** The agent proposing a step: its route and model, and its session's log. */
+interface NoteAgent {
+    readonly options: {
+        readonly provider?: string;
+        readonly model?: string;
+    };
+    readonly session: {
+        readonly id: string;
+        readonly seq?: number;
+        eventAt?(seq: number): LoggedEvent | undefined;
+    };
+}
+interface PreStep {
+    readonly agent: NoteAgent;
+    readonly step: number;
+    readonly signal: AbortSignal;
+}
+/**
+ * The last note a session's log holds, so a conversation resumed after a
+ * restart is not told twice.
+ * @param agent - the agent whose session it is.
+ * @returns the note's text, or null.
+ */
+export declare function loggedNote(agent: NoteAgent): string | null;
+/**
+ * The note for a step: on the first step of a turn on AdaptiqAI, when there is news.
+ * @param notes - the turn notes.
+ * @param route - the AdaptiqAI route.
+ * @param payload - the proposed step.
+ * @returns the note's message, or null.
+ */
+export declare function noteFor(notes: TurnNotes, route: string, payload: PreStep): Promise<UserMessage | null>;
+/**
+ * Tell each turn on AdaptiqAI which collections its conversation reads.
+ * @param ctx - a context with the `agents` service.
+ * @param workspace - the workspace.
+ * @param route - the AdaptiqAI route.
+ */
+export declare function registerKnowledgeNote(ctx: Context, workspace: Workspace, route: string): void;
+export {};

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

@@ -1,14 +1,28 @@
 import type { Context } from '@deepseek-ai/cordis';
+import type { ConversationTexts } from './conversations.ts';
 import { type Workspace } from '@adaptiqai/core';
+import { type ToolClock } from '@adaptiqai/core';
 /**
- * The media type for a file name.
+ * The media type for a file. A text of any other name (a Containerfile, a
+ * Makefile, JSON Lines, a .env) goes as plain text: sent as bytes, the
+ * engine refused it ("is not a supported source type yet") and the whole
+ * upload with it. The engine still reads a file's kind from its ending, a
+ * .tsv as a table.
  * @param name - file name.
- * @returns a media type, `text/plain` for source code.
+ * @param content - its bytes, to tell text from binary where the name does not.
+ * @returns a media type, `text/plain` for source code and other text.
  */
-export declare function mediaTypeOf(name: string): string;
+export declare function mediaTypeOf(name: string, content?: Uint8Array): string;
 /**
  * Register the AdaptiqAI agent tools.
  * @param ctx - context with the `tools` service.
  * @param workspace - the workspace.
  */
-export declare function registerTools(ctx: Context, workspace: Workspace): void;
+/**
+ * Register the agent tools.
+ * @param ctx - the plugin's context.
+ * @param workspace - the AdaptiqAI workspace.
+ * @param conversations - each conversation's history as the adapter last sent it, for find_in_conversation.
+ * @param clock - how a call waits before asking again (tests pass their own).
+ */
+export declare function registerTools(ctx: Context, workspace: Workspace, conversations?: ConversationTexts, clock?: ToolClock): void;

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

@@ -62,6 +62,8 @@ export interface WireExtras {
 export interface ReferencedSession {
     readonly sessionId: string;
     readonly label: string;
+    /** The last event of it the snapshot captured (-1 when it was empty), when the harness recorded that. */
+    readonly capturedThroughSeq?: number;
 }
 /**
  * The sessions a harness `## Referenced sessions` snapshot carries, read from
@@ -71,7 +73,8 @@ export interface ReferencedSession {
  */
 export declare function sessionReferences(message: RequestMessage): ReferencedSession[] | null;
 /**
- * Every session the request's history mentions, first mention first.
+ * Every session the request's history mentions, first mention first, each
+ * with the most of it a mention captured: a later mention shows more of it.
  * @param messages - the request history.
  * @returns unique referenced sessions.
  */
@@ -103,10 +106,39 @@ 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).
+ * The offer is recognised in core, the same in every harness.
  * @param messages - the request history.
  * @returns the person's turns, oldest first.
  */
 export declare function userTurns(messages: readonly RequestMessage[]): UserTurn[];
+/**
+ * What a turn with the knowledge tool is told about its own conversation.
+ * Asked for the fines over 40 operations notes, MiMo tried to recall every
+ * note in its reasoning, ran ten minutes and answered nothing; the tool's
+ * description spoke of saved knowledge, and it never used
+ * find_in_conversation.
+ */
+export declare const CONVERSATION_INSTRUCTIONS = "This conversation and those added to it: to count, add up or list what was said or noted earlier in them (notes, logs, figures, names), use adaptiq_knowledge, action find_in_conversation, with the words to look for, and answer from the lines it returns; for a conversation added here, give its name as conversation, or \"all\" for this one and every added one together. A long conversation is read in parts, so never count from what you remember of it.";
+/** The instructions a turn with the knowledge tool gets, collections first. */
+export declare const TURN_INSTRUCTIONS = "AdaptiqAI memory: before you answer about a specific id, name, number or date, look it up with adaptiq_knowledge, action find, with the id or the words, and answer from the lines it returns, citing document:line. Do that first: a collection this conversation uses (adaptiq_knowledge status names it) is in your memory, not on disk, so grep, glob, read and bash do not reach its documents. Each reply shows you only the part of it that matches the conversation, never all of it: documents you do not see are still there. adaptiq_knowledge is not the terminal, a local file, the web, an earlier chat or a subagent, so use it also when the person asks you to answer from memory without those. Never name a document as a source unless find or open showed it to you; if find fails, say what it answered. This conversation and those added to it: to count, add up or list what was said or noted earlier in them (notes, logs, figures, names), use adaptiq_knowledge, action find_in_conversation, with the words to look for, and answer from the lines it returns; for a conversation added here, give its name as conversation, or \"all\" for this one and every added one together. A long conversation is read in parts, so never count from what you remember of it.";
+/**
+ * Whether a message is one the person wrote: typed, or a reply to the
+ * agent's question. The harness also sends the user role its own context
+ * (instructions, skills, checkpoints, the plugin's notes, conversations
+ * mentioned with @), and the agent's replies repeat figures: counted
+ * together, one typed fine became three.
+ * @param message - a message of the request history.
+ * @returns whether the person wrote it.
+ */
+export declare function personWrote(message: RequestMessage): boolean;
+/**
+ * A conversation's own messages as lines, for find in it: what the person
+ * wrote, each message headed with its number, its text a line each, an empty
+ * line after it.
+ * @param messages - the request history, as the harness sent it.
+ * @returns the lines.
+ */
+export declare function conversationLines(messages: readonly RequestMessage[]): string[];
 /**
  * Convert the harness history to Chat Completions messages.
  * @param options - the harness request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptiqai/deepseek-harness",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "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",
@@ -90,7 +90,7 @@
     "react-dom": "~18.3.1",
     "typescript": "~5.9.3",
     "vitest": "~3.2.7",
-    "@adaptiqai/core": "0.2.14"
+    "@adaptiqai/core": "0.2.16"
   },
   "repository": {
     "type": "git",