Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: make technical prose concrete

Browse Source
This commit is contained in:
Turtle
2026-08-09 15:27:21 +08:00
parent 673e7cddc5
commit a27efdef36
459 changed files with 1342 additions and 1329 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
packages/llm/llm/src/index.ts
View File

@@ -184,8 +184,8 @@ export interface PreparedLlmCall {
/**
* Provider-wire adapter for the harness message and stream vocabulary. Register implementations
* with `ctx.llm.registerAdapter(providers, adapter)`. Every provider HTTP request must include
* `attributionHeaders()`; prove that at the wire or library header-hook boundary. The direct-fetch
* DeepSeek and library-backed pi-ai adapters intentionally exercise this contract through different internals.
* `attributionHeaders()`; prove the headers are added in the wire request or library header hook. The direct-fetch
* DeepSeek and library-backed pi-ai adapters meet this contract through different internals.
*/
export abstract class LlmAdapter {
/**

10
packages/llm/llm/src/message.ts
View File

@@ -30,8 +30,8 @@ export interface ToolMessageSource {
}
/**
* What SHAPE of information a producer-supplied context carries, declared by
* the producer beside the source fields it supplied.
* The kind of information in producer-supplied context, declared by the
* producer beside its provenance.
*
* `MessageSource.kind` answers *who produced this*; `form` answers *what kind
* of thing it is*, and the two axes are deliberately independent — several
@@ -69,10 +69,10 @@ export interface ContextSnapshotSection {
/**
* Producer-declared {@link ContextForm} and the fields that form requires,
* mixed into the source shapes that carry one.
* mixed into the source types that carry one.
*
* Discriminated by `form` so a producer cannot declare a shape without the
* facts that shape is presented from: a `notice` must record its one-line
* Discriminated by `form` so a producer cannot select a form without the
* fields needed to present it: a `notice` must record its one-line
* account, a `snapshot` its sections. Omitting `form` stays valid — an
* undeclared context is the documented default.
*/

8
packages/llm/llm/src/types.ts
View File

@@ -1,6 +1,6 @@
/**
* Canonical provider-neutral message and streaming vocabulary for the loop,
* session log, and plugins. Adapters alone translate provider wire shapes;
* session log, and plugins. Adapters alone translate provider wire messages;
* mapped interfaces make the content, source, and finish unions extensible.
*/
@@ -21,13 +21,13 @@ export type {
UserMessage,
} from './message.ts'
/** Serializable provider-boundary facts; policy decides whether they are retryable. */
/** Serializable provider or transport failure facts; policy decides whether they are retryable. */
export interface LlmFailure {
/** Human-readable provider or transport failure. */
readonly message: string
/** Stable provider-neutral machine-routing code. */
readonly code: string
/** HTTP status observed at the provider boundary, when available. */
/** HTTP status returned by the provider, when available. */
readonly status?: number
/** Provider-requested delay in milliseconds, when valid and available. */
readonly providerRetryAfterMs?: number
@@ -89,7 +89,7 @@ export interface ContentBlockMap {
'tool-result': ToolResultBlock
}
/** The block `type` tag vocabulary; widens as plugins merge new shapes into {@link ContentBlockMap}. */
/** The block `type` tag vocabulary; widens as plugins add entries to {@link ContentBlockMap}. */
export type ContentBlockType = keyof ContentBlockMap
/** Any known content block, derived from {@link ContentBlockMap}; switch on `type` and fall through unknowns (merge-extensible). */
export type ContentBlock = ContentBlockMap[ContentBlockType]