Python
export const CORE_SERVICE = "one-memory-core" as const;
/**
* The one host-id grammar.
*
* A host id is an opaque label for the app a recall grant belongs to. It is
* never a path component: the permission layer keys an installation by a
* digest of the whole id, so a colon is a label separator, not a directory
* separator.
*
* One app can be configured per profile, which is the reason for the single
* optional `:<profile>` segment — DeepSeek Harness reports
* `deepseek-harness:<profile>` and `host list` prints those ids.
*
* The CLI, the permission layer and the grant store all have to read the same
* shape: an id that `host list` prints must be an id `host install` accepts.
* There is one definition here rather than three regexes that drift.
*/
const HOST_SEGMENT_MAX = 64;
const PROFILE_SEGMENT_MAX = 32;
/**
* Lower-case letters, digits and hyphens; first character alphanumeric; at
* most one `:` followed by an alphanumeric-first profile segment.
*
* The trailing `(?![\s\S])` is "end of input". `$` alone would also match
* before a final newline, so `"codex\n"` would pass a pattern a caller reads
* as an exact match.
*/
export const HOST_ID_PATTERN = new RegExp(
`^[a-z0-9][a-z0-9-]{0,${HOST_SEGMENT_MAX - 1}}(?::[a-z0-9][a-z0-9-]{0,${PROFILE_SEGMENT_MAX - 1}})?(?![\\s\\S])`,
);
/** Longest id the grammar can produce: host + ":" + profile. */
export const HOST_ID_MAX_LENGTH = HOST_SEGMENT_MAX + 1 + PROFILE_SEGMENT_MAX;
export function isHostId(value: unknown): value is string {
return (
typeof value === "string" &&
value.length <= HOST_ID_MAX_LENGTH &&
HOST_ID_PATTERN.test(value)
);
}
export type {
ConnectionSetupCapability,
ConnectionSetupExecute,
ConnectionSetupItem,
ConnectionSetupItemState,
ConnectionSetupJournal,
ConnectionSetupPreview,
ConnectionSetupResult,
ConnectionSetupSelection,
} from "./connection-setup.js";
export interface HealthResponse {
status: "ok";
service: typeof CORE_SERVICE;
version: string;
instance_id: string;
/**
* Whether Core is still catching up on conversations imported before it had
* a model to read them with. Not a degraded state: recall answers
* throughout. Absent from cores older than this field.
*/
memory_backfill?: "running" | "done" | "failed";
memory_backfill_error?: string | null;
/**
* Work an earlier run left unfinished (write queue, interrupted imports,
* live sync) is picked up after Core is ready. "running" is not degraded:
* readiness never waits for it. Absent from cores older than this field.
*/
recovery?: "pending" | "running" | "done" | "failed";
recovery_failed_steps?: string[];
}
export type ImportStatus =
| "pending"
| "running"
| "paused"
| "interrupted"
| "completed"
| "failed"
| "cancelled";
export type ScanPhase = "discover" | "read" | "emit" | "done";
export interface HostPackageCapabilities {
historical_import: "not_implemented" | "implemented";
incremental_import: "not_implemented" | "implemented";
live_sync: "not_implemented" | "implemented";
recall: "not_implemented" | "implemented";
installer: "not_implemented" | "implemented";
verification: "fixture_only" | "real_replayed";
}
/**
* How much of a source's own changes a live connection can follow.
*
* A source we can only read forward from never tells us something was deleted
* upstream, so the user has to be told they are getting additions only rather
* than a copy that tracks the source.
*/
export type SyncCompleteness =
| "full_dynamic"
| "additions_only"
| "one_time_snapshot";
export interface SourceImportReceipt {
source_id: string;
measured_at: string;
messages: number;
conversations: number;
person_messages: number;
agent_messages: number;
tool_messages: number;
unknown_author_messages: number;
unknown_time_messages: number;
/** Bounded deterministic human-query samples, not a live job event feed. */
query_examples?: Array<{
evidence_id: string;
evidence_revision: number;
role: string;
written_by: string;
created_at: string | null;
excerpt: string;
truncated: boolean;
query_start: number;
query_end: number;
projection_version: number;
}>;
examples: Array<{
evidence_id: string;
role: string;
written_by: string;
created_at: string | null;
excerpt: string;
truncated: boolean;
}>;
}
/** Why a source cannot be read right now.
*
* `authorized: false` alone could not be acted on: a grant that was never
* made, one that was revoked, and a history directory that moved all need a
* different thing from the user, and used to get the same advice. Absent on a
* Core that does not report it, which then means "not measured".
*/
export type SourceAuthorizationState =
| "ok"
| "missing_grant"
| "revoked_grant"
| "source_identity_changed"
| "source_root_unavailable"
| "candidate_changed";
export interface SourceResponse {
source_id: string;
display_name: string;
storage_kinds: string[];
available: boolean;
authorized: boolean;
authorization_state?: SourceAuthorizationState;
detected: boolean | null;
root_label: string | null;
candidate_path: string;
candidate_kind: "default" | "environment_override" | "user_selected";
candidate_revision?: number;
candidate_change_allowed?: boolean;
candidate_change_reason?: string | null;
imported_messages: number;
imported_conversations: number;
capabilities: HostPackageCapabilities;
sync_completeness: SyncCompleteness;
grant_revision?: number;
root_id?: string | null;
sync_enabled: boolean;
location_state?: "found" | "not_found" | "inaccessible" | "invalid";
candidate_root_id?: string | null;
/** How many sessions the detect walk found at this source's root.
*
* Present only on cores that report it. Absent or null means "not measured"
* rather than zero, so the UI must not print a number it was not given.
*/
session_count?: number | null;
}
export interface SourceDirectoryCandidate {
source_id: string;
path: string;
root_id: string;
candidate_revision: number;
}
export interface SourceGrantReceipt {
user_id: string;
source_id: string;
root_id: string;
root_label: string;
candidate_kind: "default" | "environment_override" | "user_selected";
granted_at: string;
revoked_at: string | null;
revision: number;
}
export interface SourceSyncRequest {
enabled: boolean;
}
export interface SourceSyncState {
source_id: string;
sync_enabled: boolean;
}
/** Whether the configured model may read locally stored conversation content. */
export interface ModelContentPermission {
allowed: boolean;
}
export interface DetectionResponse {
source_id: string;
detected: boolean;
}
export interface ConnectSourcesResponse {
accepted_source_ids: string[];
failed_sources: Record<string, string>;
jobs: ImportJob[];
request_id?: string | null;
}
export interface OnboardingState {
status: "not_started" | "importing" | "completed";
selected_source_ids: string[];
started_at: string | null;
completed_at: string | null;
}
export interface ImportJob {
job_id: string;
user_id: string;
source_id: string;
/** Present in current Core responses; older versions imply history. */
operation?: "history" | "sync";
status: ImportStatus;
phase: ScanPhase | null;
checkpoint: string | null;
discovered: number;
discovered_targets: number;
emitted: number;
stored: number;
revised: number;
merged: number;
skipped: number;
errors: number;
created_at: string;
updated_at: string;
/** Shared lower bound for a volume-limited first import; absent means full history. */
history_after?: string | null;
}
export interface ImportIssue {
issue_id: number;
job_id: string;
kind: "error" | "skip";
conversation_id: string | null;
reason: string;
created_at: string;
}
export type ProviderKind =
| "hy_default"
| "openai_compatible"
| "anthropic"
| "ollama"
| "local_onnx";
export interface ModelCapabilities {
endpoint_reachable: boolean;
model_available: boolean;
structured_output: boolean;
embedding_available: boolean;
}
export interface ModelProfile {
profile_id: string;
name: string;
provider_kind: ProviderKind;
base_url: string | null;
model: string;
embedding_model: string | null;
embedding_provider_kind: ProviderKind | null;
embedding_base_url: string | null;
embedding_dimensions: number | null;
has_api_key: boolean;
has_configured_api_key?: boolean;
credential_state?: "available" | "missing" | "unavailable";
timeout_seconds: number;
max_concurrency: number;
context_window: number | null;
disable_thinking: boolean;
capabilities: ModelCapabilities;
revision: number;
is_active: boolean;
created_at: string;
updated_at: string;
}
export interface ModelProfileInput {
creation_operation_id?: string;
name: string;
provider_kind: ProviderKind;
base_url?: string | null;
model: string;
embedding_model?: string | null;
embedding_provider_kind?: ProviderKind | null;
embedding_base_url?: string | null;
embedding_dimensions?: number | null;
api_key?: string;
timeout_seconds?: number;
max_concurrency?: number;
context_window?: number | null;
disable_thinking?: boolean;
}
export interface ModelCreationOperation {
operation_id: string;
state: "committed" | "pending" | "deleted" | "not_found";
profile_id: string | null;
created_revision: 1 | null;
}
/**
* A partial change to a saved profile. `expected_revision` is required: the
* core rejects a write aimed at a revision that has since moved rather than
* silently overwriting whatever is there now.
*/
export interface ModelProfilePatch {
expected_revision: number;
name?: string;
base_url?: string | null;
model?: string;
embedding_model?: string | null;
embedding_provider_kind?: ProviderKind | null;
embedding_base_url?: string | null;
embedding_dimensions?: number | null;
api_key?: string;
clear_api_key?: boolean;
timeout_seconds?: number;
max_concurrency?: number;
context_window?: number | null;
disable_thinking?: boolean;
}
export type ProbeCode =
| "ok"
| "hy_default_unavailable"
| "missing_api_key"
| "unreachable"
| "unauthorized"
| "rate_limited"
| "insufficient_balance"
| "model_not_found"
| "model_list_unsupported"
| "invalid_response"
| "structured_output_unsupported"
| "embedding_model_required"
| "embedding_unavailable";
export interface ModelProbeResult {
profile_id: string;
profile_revision: number;
/** Revision read at probe admission; a measured embedding width may advance the result revision. */
input_profile_revision?: number | null;
stages: Array<{
stage: string;
ok: boolean;
code: ProbeCode;
latency_ms: number;
}>;
capabilities: ModelCapabilities;
}
export interface ModelProbeOperationRequest {
operation_id: string;
expected_profile_revision: number;
}
export interface ModelProbeOperationReceipt {
schema_version: 1;
operation_id: string;
profile_id: string | null;
expected_profile_revision: number | null;
state: "pending" | "completed" | "failed" | "not_found";
result: ModelProbeResult | null;
code: "model_probe_profile_changed" | "model_probe_execution_failed" | null;
stale: boolean | null;
}
// biome-ignore format: test_contract_parity.py reads this union from a single line.
export type MemoryStatus = "confirmed" | "deleted" | "superseded";
export type MemoryKind = "chat" | "working" | "coding" | "schema" | "intention";
/** Who wrote the sentence, as against `kind`, which is what it is about.
*
* Read by recall: a summary a model composed should not reach another app
* looking like something the person said. */
export type MemoryOrigin = "extracted" | "answered" | "agent" | "manual";
/** Local homepage projection; not a host-specific recall permission. */
export interface HomeSummary {
memory_count: number;
latest: {
memory_id: string;
content: string;
truncated: boolean;
revision: number;
action?: "create" | "correct" | "delete" | "restore" | "unknown";
updated_at: string;
source_ids: string[];
} | null;
observed_at: string;
/** 2026-10-12: 本轮读取超时,数字不代表现状;调用方应保留上一次的数据。 */
stale?: boolean;
}
export interface SdkHomeSummary {
schema_version: 2;
memory_count: number;
latest: SdkMemoryRecord | null;
observed_at: string;
}
export type HostHomeSummary = HomeSummary | SdkHomeSummary;
export interface GovernedMemory {
memory_id: string;
user_id: string;
kind: MemoryKind;
status: MemoryStatus;
content: string;
scopes: string[];
evidence_ids: string[];
origin: MemoryOrigin;
/** HY's own topic tags, free-form and possibly empty.
*
* Not a closed set. HY seeds its extract prompt with the tags already in
* the library so the model reuses them, but nothing stops it minting a new
* one, which is how every product that tried this ended up with `Goals` and
* `goal` side by side. Read as a proposal, not a taxonomy. */
tags: string[];
/** Memories HY replaced with this one, and memories that replaced it.
* A memory with `superseded_by` is kept for reading but is no longer current. */
supersedes?: string[];
superseded_by?: string[];
revision: number;
created_at: string;
updated_at: string;
deleted_at: string | null;
}
export type ExtractionState = "extracted" | "outside_window" | "queued";
/** Local UI projection; source permissions apply before both count and paging. */
export interface MemoryLibraryPage {
items: GovernedMemory[];
total: number;
offset: number;
limit: number;
/** Active evidence sources for each returned memory, from the same authorized page snapshot. */
source_ids_by_memory?: Record<string, string[]>;
/** When each returned memory's cited conversation happened (D96). `import`
* when only the import time is known; `write` for an SDK experience or fact
* stored without a conversation time, which shows when it was written. */
source_time_by_memory?: Record<
string,
{ at: string; basis: "conversation" | "import" | "write" }
>;
/** True when the read budget ran out mid-page (typically during a history
* import): a partial snapshot, not an authoritative view. Show "importing"
* and retry; never render this state as a failure. */
stale?: boolean;
/** Set on a search whose relevance window was full: matches were looked for
* only among this many most relevant memories, so `total` may undercount. */
search_window?: number | null;
/** SDK keyword search: the server-side result window to page with. */
window_id?: string | null;
/** SDK keyword search: the window passed in had expired, so this is page 1
* of a fresh search. */
window_reset?: boolean;
/** SDK pages: which scene each returned memory is from, and the namespace
* to name when opening, editing or deleting it. */
sdk_memory_refs?: Record<string, SdkMemoryRef>;
}
export interface MemoryLibraryQuery {
query?: string;
status?: MemoryStatus;
active_only?: boolean;
source?: string;
offset?: number;
limit?: number;
}
export type ExtractionWindowPreset = "3m" | "6m" | "1y" | "all";
export interface MemoryEvidenceExcerpt {
evidence_id: string;
available: boolean;
source_id: string | null;
role: string | null;
written_by: string | null;
created_at: string | null;
verbatim: string | null;
extraction_state?: ExtractionState | null;
}
export interface MemoryVersion {
memory_id: string;
revision: number;
action: string;
status: MemoryStatus;
content: string;
scopes: string[];
created_at: string;
}
export type MemoryIndexSyncStatus = "pending" | "synced";
export interface MemoryIndexSync {
memory_id: string;
status: MemoryIndexSyncStatus;
attempts: number;
last_error_code: string | null;
updated_at: string;
}
export interface MemoryDetail {
memory: GovernedMemory;
evidence: MemoryEvidenceExcerpt[];
history: MemoryVersion[];
/** SDK-native display metadata. Legacy governed details leave these absent. */
sdk_status?: SdkMemoryStatus;
source_id?: string | null;
sdk_memory_at?: string | null;
sdk_created_at?: string | null;
/** SDK memories: the namespace to name on edit/delete. */
sdk_ref?: SdkMemoryRef;
/** SDK experiences: the task and solution, edited apart. */
sdk_task?: string | null;
sdk_solution?: string | null;
// Null for a memory nobody has rewritten: there is no index to be behind,
// and the interface should not explain a state the user never caused.
index_sync: MemoryIndexSync | null;
}
export type SdkMemoryStatus =
| "active"
| "superseded"
| "shadow"
| "negated"
| "conflicted"
| "archived";
/** Which part of the library a memory lives in. */
export type SdkMemoryScene = "chat" | "working" | "coding";
/** What the memory is: a chat memory, a working/coding experience or fact. */
export type SdkMemoryKind = "chat" | "experience" | "fact";
/** The productivity namespace of an experience or fact. */
export type SdkMemoryVariant = "working" | "coding";
/** Enough to address one memory again: get/update/delete pass kind+variant. */
export interface SdkMemoryRef {
scene: SdkMemoryScene;
kind: SdkMemoryKind;
variant: SdkMemoryVariant | null;
}
export interface SdkMemoryRecord {
memory_id: string;
content: string;
layer: string;
status: SdkMemoryStatus;
is_latest: boolean;
supersedes: string[];
superseded_by: string[];
tags: string[];
owner: string | null;
source_raw_ids: string[];
user_id: string;
agent_id: string;
session_id: string | null;
source: string | null;
memory_at: number | null;
gmt_created: number | null;
/** Absent only from pre-2.0.6 Core responses, which were all chat. */
scene?: SdkMemoryScene;
kind?: SdkMemoryKind;
variant?: SdkMemoryVariant | null;
/** Experiences: the task and the solution; `content` is both, joined. */
task?: string | null;
solution?: string | null;
/** Epoch seconds. */
created_at?: number | null;
updated_at?: number | null;
}
export interface SdkMemoryPage {
memories: SdkMemoryRecord[];
total: number;
limit: number;
offset: number;
search_window?: number | null;
/** Keyword search: pass back with the next offset to page the same
* results. Null on a plain listing. */
window_id?: string | null;
/** Keyword search: the window_id sent had expired or did not match, the
* search ran again and this page is page 1 (offset 0) of the new window. */
window_reset?: boolean;
/** Plain listing: memories per scene under the same filters. */
totals?: Partial<Record<SdkMemoryScene, number>> | null;
}
export interface SdkUserProfileResponse {
request_id: string;
profile: Record<string, unknown> | null;
elapsed_ms: number;
}
export interface SdkRawRecord {
raw_id: string;
content: string;
user_id: string;
agent_id: string;
session_id: string;
source: string;
memory_at: number | null;
gmt_created: number | null;
custom: Record<string, unknown>;
/** active, or shadow once pro extracted it. */
status?: string | null;
/** The turn's messages, parsed from the SDK's `[role]: text` lines. */
messages?: { role: string; content: string }[];
/** The one role of a single-message turn; null for a mixed turn. */
role?: string | null;
/** `sha256:<hex>` of the stored content, computed by Core. */
content_hash?: string;
/** ISO time the SDK stored the raw. */
created?: string | null;
}
export interface SdkRawPage {
items: SdkRawRecord[];
total: number;
limit: number;
offset: number;
/** A time range was applied to this page in Core (the SDK list has none). */
time_filtered?: boolean;
}
/** `GET /api/v2/memory-library/layers`: memories per SDK layer. */
export interface SdkLayerCounts {
layers: Record<string, number>;
total: number;
statuses: string[] | null;
}
/** `GET /api/v2/user-profile/versions`: the L0 basic-info version chains. */
export interface SdkProfileVersions {
user_id: string;
request_id: string;
elapsed_ms: number;
chains: {
memory_id: string;
content: string;
status: string;
memory_at: number | null;
gmt_created: number | null;
basic_info: Record<string, unknown>;
versions: {
memory_id: string;
content: string;
memory_at: number | string | null;
gmt_created: number | null;
current: boolean;
}[];
}[];
}
export interface FileImportReceipt {
upload_id: string;
filename: string;
vendor: "chatgpt" | "claude" | "generic" | "memory-content";
content_kind?: "raw_conversation" | "memory_content";
source_id: string;
messages: number;
conversations: number;
human_messages: number;
agent_messages: number;
unknown_author_messages?: number;
skipped_records: number;
ignored_files: number;
checksum: string;
created_at: string;
committed: boolean;
preview?: Array<{
role: string;
written_by?: "person" | "agent" | "unknown" | "tool";
text: string;
created_at: string | null;
truncated: boolean;
}>;
}
export interface FileImportOperationReceipt {
schema_version: 1;
operation_id: string;
state: "not_found" | "pending" | "completed" | "failed";
upload_id: string | null;
code: "import_upload_invalid" | null;
upload_state: "staged" | "committed" | "missing" | "unknown" | null;
}
export interface AskMemoryRequest {
question: string;
scope?: string;
/** Same host-injected directory as recall; never a model-supplied path. */
workspace_path?: string;
}
export interface AskMemoryResponse {
answer: string;
memories: GovernedMemory[];
mode: "generated" | "extractive" | "empty";
}
export interface SdkAskMemory {
memory_id: string;
content: string;
layer: string;
status: string;
source: string | null;
gmt_created: number | null;
}
export interface SdkAskMemoryResponse {
schema_version: 2;
answer: string;
memories: SdkAskMemory[];
mode: "generated" | "extractive" | "empty";
}
export type HostAskMemoryResponse = AskMemoryResponse | SdkAskMemoryResponse;
export type AskMemoryEvent =
| { type: "recall"; memories: GovernedMemory[] }
| { type: "delta"; text: string }
| {
type: "final";
answer: string;
memories: GovernedMemory[];
mode: "generated" | "extractive" | "empty";
}
| { type: "error"; code: string };
export type SdkAskMemoryEvent =
| { type: "recall"; memories: SdkAskMemory[] }
| { type: "delta"; text: string }
| {
type: "final";
schema_version: 2;
answer: string;
memories: SdkAskMemory[];
mode: "generated" | "extractive" | "empty";
}
| { type: "error"; code: string };
export type HostAskMemoryEvent = AskMemoryEvent | SdkAskMemoryEvent;
export interface RecallRequest {
query: string;
scope?: string;
limit?: number;
character_budget?: number;
/** Wall-clock budget for candidate gather + score (ms). */
timeout_ms?: number;
/** The directory the caller is working in.
*
* A scope string cannot be produced outside Core, so this is how a caller
* reaches the memories from the project it is in. Naming its own directory
* is all it can do: no other workspace becomes readable. */
workspace_path?: string;
}
export interface RecallHit {
/** A memory id, or in raw mode the id of the original conversation excerpt. */
memory_id: string;
content: string;
/** `hy-sdk` means content already includes SDK-rendered logical time/history.
* `raw` means an original conversation excerpt, not a memory. */
content_format?: "plain" | "hy-sdk" | "raw";
/** `raw` only in raw mode: an excerpt carries no evidence ids and no scopes. */
kind: MemoryKind | "raw";
/** The app an excerpt came from (raw mode). */
source?: string | null;
/** The conversation an excerpt came from (raw mode). */
session_id?: string | null;
scopes: string[];
evidence_ids: string[];
updated_at: string;
score: number;
}
export type TruncationBudget =
| "count_budget"
| "character_budget"
| "timeout_budget";
export interface RecallReceipt {
state: "grounded" | "empty";
query: string;
scope: string;
hits: RecallHit[];
used_characters: number;
truncated: boolean;
/** Which parallel budget fired when `truncated` is true. */
truncated_by?: TruncationBudget | null;
/** Scored (or known surplus) candidates left unreturned. */
unexamined_count?: number;
/** Absent means `memory`. `raw` means Core searched imported original
* conversations instead, and the hits are excerpts, not confirmed memories. */
mode?: "memory" | "raw";
/** Why recall fell back to raw conversations. */
fallback_reason?: "model_unavailable" | "no_memories" | null;
/** Sources the caller was not allowed to read, left out of this result. */
excluded_sources?: string[];
}
export interface LiveSyncHealth {
source_id: string;
// Watching is layered on top of the timer rather than replacing it, so the
// mode names both: the timer still covers what the watch rate limit skipped.
mode: "polling" | "watch_and_polling";
state: "idle" | "running" | "degraded" | "unavailable";
last_job_id: string | null;
last_attempt_at: string | null;
last_success_at: string | null;
last_error_code: string | null;
}
export interface MemoryGraphNode {
node_id: string;
node_type: "memory" | "source" | "schema" | "topic";
label: string;
memory_id: string | null;
source_id: string | null;
kind: string | null;
status: string | null;
confidence: number | null;
}
export interface MemoryGraphEdge {
edge_id: string;
source_node_id: string;
target_node_id: string;
relation: string;
weight: number | null;
origin:
| "provenance"
| "same_conversation"
/** Two memories carrying the same tag. Only drawn where a tag is shared,
* so a topic on the map always has more than one memory under it. */
| "shared_tag"
| "hy_relation";
}
export interface MemoryGraphResponse {
total_memories: number;
projected_memories: number;
nodes: MemoryGraphNode[];
edges: MemoryGraphEdge[];
hy_graph_available: boolean;
}
export interface MemoryProcessingBlock {
kind: string;
reason: string;
count: number;
}
export interface MemoryProcessingSummary {
pending: number;
/** `pending` split by how recent the evidence is: what arrived today, and
* the import catch-up behind it. One total reads as "stuck". */
fresh_pending: number;
backlog_pending: number;
/** Evidence kept out of automatic extraction by the window. */
outside_window_pending: number;
/** When work last landed, newest first. */
recent_completions: string[];
/** Rows the task store marks `running`.
*
* **Not the current concurrency.** A task is marked running before anything
* slow happens, so a worker that later gives up — a timeout, a crash between
* steps — leaves its row here until something recovers it. This number can
* therefore stay above zero while nothing is actually running.
*
* For "how much is running now" use `in_flight_count`. What this is good for
* is the opposite question: how many look running but are not. */
running: number;
/** Rows marked `running` that no worker currently owns.
*
* The difference between `running` and `in_flight_count`, floored at zero.
* Non-zero means work is stranded: those tasks hold their harness's slot
* until they are recovered, and a harness is serial, so nothing else from
* that harness can run behind them. */
/* Optional so that existing producers and fixtures stay valid; Core always
* sends it, and a reader that does not see it should treat it as unknown
* rather than as zero. */
stranded_running?: number;
/** Failed and never attempted because the continuous policy was not in
* force. Included in `failed`, but not a real extraction failure: nothing
* was sent to HY. A revoked policy otherwise reads as a broken pipeline. */
unexecuted_policy_failures?: number;
waiting_for_model: number;
completed: number;
failed: number;
/** Tasks whose HY outcome cannot be proven yet. */
unknown?: number;
unknown_reasons?: Record<string, number>;
blocked_stages: MemoryProcessingBlock[];
seconds_per_completion: number | null;
extraction_window_preset: ExtractionWindowPreset;
manual_extract_batches_planned: number;
manual_extract_batches_current: number;
/** Work admitted to the bounded scheduler window. */
active_queue: number;
/** Memory tasks currently owned by workers — the real concurrency.
*
* Workers own a task from the moment they take it until they finish, fail or
* give up, so unlike `running` this cannot include work nobody is doing. */
in_flight_count: number;
metrics?: {
raw_evidence: number;
complete_turns: number;
hy_calls: number;
completed: number;
unknown: number;
failed: number;
cancelled: number;
cancelled_reasons: Record<string, number>;
governed_memories: number;
workbuddy: { injected: number; timed_out: number; unavailable: number };
};
}
export interface ExtractionSettings {
window_preset: ExtractionWindowPreset;
}
export type GraphWidthDecision =
| "keep_existing"
| "rebuild_with_new"
| "export_first";
export interface GraphWidthMismatch {
stored_width: number;
expected_width: number;
graph_path: string;
}
export interface GraphWidthStatus {
mismatch: GraphWidthMismatch | null;
memory_count: number;
}
export interface GraphWidthDecisionReceipt {
archived_path: string | null;
exported_path: string | null;
mismatch: GraphWidthMismatch | null;
}
export interface ConversationSearchHit {
evidence_id: string;
conversation_id: string;
source_id: string;
workspace: string | null;
project: string | null;
created_at: string | null;
excerpt: string;
/** Who the matched row belongs to. Present for a hit on a stored row, where
* both columns are NOT NULL on `evidence`. Absent when the list was built
* from a conversation summary instead: a whole conversation has no single
* author, and a client must not invent one. */
role?: string | null;
written_by?: string | null;
title?: string | null;
turn_count?: number | null;
memory_count?: number | null;
turn_offset?: number | null;
}
/**
* Why a search came back empty. Null whenever there are hits; a search that
* cannot run at all answers 503 instead, so the interface never has to guess
* which of the three states it is looking at.
*/
export type ConversationSearchEmptyReason = "no_matches" | "nothing_imported";
export interface ConversationSearchResponse {
hits: ConversationSearchHit[];
empty_reason: ConversationSearchEmptyReason | null;
imported_messages: number;
}
export interface ConversationMessage {
evidence_id: string;
role: string;
written_by: string;
created_at: string | null;
verbatim: string;
turn_index?: number;
system_context?: boolean;
}
export interface ConversationTranscript {
conversation_id: string;
source_id: string;
messages: ConversationMessage[];
total_turns?: number;
offset?: number;
limit?: number;
has_more?: boolean;
/** The last turn asked something and got nothing back yet. It is imported
* and shown, but nothing about it is settled enough to draw a memory from. */
trailing_turn_unanswered?: boolean;
}
export interface ConversationSummary {
evidence_id: string;
conversation_id: string;
source_id: string;
workspace: string | null;
project: string | null;
title: string;
latest_at: string;
turn_count: number;
memory_count: number;
}
export interface ConversationBrowserPage {
items: ConversationSummary[];
total: number;
offset: number;
limit: number;
}
export interface ConversationMemories {
items: GovernedMemory[];
}
/** One imported message, newest import first. Not a governed memory. */
export interface RecentConversationItem {
evidence_id: string;
conversation_id: string;
source_id: string;
role: string;
written_by: string;
created_at: string | null;
imported_at: string;
time_basis: "conversation" | "import";
excerpt: string;
truncated: boolean;
}
export interface RecentConversationsPage {
items: RecentConversationItem[];
total: number;
offset: number;
limit: number;
}
export interface ManualExtractReceipt {
promoted: number;
batches_planned: number;
batches_current: number;
}
/** Body of `POST /api/v2/memories`: add one memory directly. */
export interface MemoryAddInput {
request_id: string;
text: string;
scope: "all-apps";
}
/** Receipt of `POST /api/v2/memories` and
* `GET /api/v2/memories/additions/{request_id}`. */
export interface MemoryAddReceipt {
evidence_id: string;
text: string;
scope: "all-apps";
created_at: string;
state:
| "waiting_for_model"
| "waiting_for_permission"
| "pending"
| "running"
| "failed"
| "ready"
| "no_memories";
task_id: string | null;
memory_ids: string[];
error: string | null;
}
export type {
BackupRestoreFailureCode,
BackupRestoreRequest,
BackupRestoreResult,
} from "./backup-restore.js";
export type {
ContextItem,
ContextKind,
ContextLimit,
ContextMessage,
ContextPath,
ContextReason,
ContextSearchRequest,
ContextSearchResponse,
HostContextSearchResponse,
MemoryContextItem,
RawContextItem,
SdkContextItem,
SdkContextSearchResponse,
SdkMemoryContextItem,
SdkRawContextItem,
} from "./context.js";
export type {
ContextExpandRequestV2,
ContextHintsV2,
ContextRequestV2,
ContextSearchRequestV2,
EvidenceGroupV2,
EvidenceItemV2,
EvidenceSpanV2,
GovernedEvidenceV2,
ObjectReferenceV2,
RawEvidenceV2,
RetrievalChannel,
RetrievalIntent,
RetrievalLimit,
RetrievalPathV2,
RetrievalResponseV2,
RetrievalTimeRange,
} from "./context-v2.js";
export type {
Citation,
Matter,
MatterClaim,
MatterContext,
MatterEvidence,
MatterPatch,
MatterRun,
} from "./matters.js";
export type {
UISessionExchange,
UISessionFailureCode,
UISessionLogout,
} from "./ui-session.js";