@aexol/spectral 0.8.0 → 0.8.5

package/dist/memory/prompts.d.ts

@@ -0,0 +1,11 @@
+export declare const MEMORY_STAKES = "These records are the ONLY information the assistant will have about past interactions once the raw conversation is compacted out of context. Anything you do not capture here will be forgotten. Anything you distort here will be remembered wrong. Take this seriously.";
+export declare const OBSERVATION_CONTENT_RULES = "Observation content rules:\n\nFormat.\n- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.\n- Do NOT include the timestamp or relevance inside the content string \u2014 those are separate fields.\n- No structured fields embedded in the text (no \"key: value\" lines, no JSON).\n\nPreserve user assertions exactly.\nWhen the user TELLS you something about themselves, their project, or their environment, capture it as an assertion. When the user ASKS something, capture it as a question. Assertions are authoritative \u2014 a later question on the same topic does not invalidate them.\n  BAD:  User wondered if they have two kids.\n  GOOD: User stated they have two kids.\n  BAD:  User discussed auth middleware.\n  GOOD: User asked how to configure JWT auth middleware.\nWhy this matters: if the user says \"I use Postgres\" and later asks \"what db am I on?\", downstream agents must treat the assertion as the answer, not the question.\n\nPreserve unusual phrasing.\nWhen the user uses non-standard terminology, quote their exact words so future runs can recognize the term.\n  BAD:  User exercised yesterday.\n  GOOD: User stated they did a \"movement session\" (their term) yesterday.\n\nUse precise action verbs. Replace vague verbs with ones that clarify the nature of the action.\n  BAD:  User got a new subscription.\n  GOOD: User subscribed to the Pro plan.\n  BAD:  User stopped getting the newsletter.\n  GOOD: User unsubscribed from the newsletter.\n  BAD:  User got the library.\n  GOOD: User installed the zod package via pnpm.\n\nFrame state changes as supersession so the old state is explicit.\n  BAD:  User prefers React Query now.\n  GOOD: User will use React Query (switching from SWR).\nWhy this matters: without supersession framing, the reflector may crystallize both the old and the new as equally valid preferences.\n\nMark concrete completions explicitly.\nUse \"completed:\", \"resolved:\", \"confirmed working\", or similar phrasing so future runs know not to redo the work.\n  BAD:  Wrote the login handler.\n  GOOD: completed: implemented login handler at src/auth/login.ts; user confirmed tests pass.\nWhy this matters: without a completion marker, a later assistant may re-implement work that is already done, wasting the user's time and risking regressions.\n\nSplit compound statements into separate observations.\nIf a single message contains multiple independent facts, intents, or events, emit one observation per fact. One observation per line is what enables downstream retrieval and pruning to operate at fact granularity.\n  BAD:  User will visit their parents this weekend and needs to clean the garage.\n  GOOD: User will visit their parents this weekend. + User stated they need to clean the garage this weekend.\n  BAD:  User started a new job and is moving to a new apartment next week.\n  GOOD: User started a new job. + User will move to a new apartment next week.\n  BAD:  Assistant recommended Lucia, NextAuth, and Clerk for auth, and user chose Lucia.\n  GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid). + User chose Lucia.\nWhy this matters: a future query like \"which auth library did the user pick?\" can match a single-fact observation cleanly; a compound observation hides the decision inside a recommendation list.\n\nGroup repeated similar tool calls into a single observation rather than one per call.\n  BAD:  Agent viewed src/auth.ts. Agent viewed src/users.ts. Agent viewed src/routes.ts.\n  GOOD: Agent surveyed auth-related files (src/auth.ts, src/users.ts, src/routes.ts) and located token validation in src/auth.ts:45.";
+export declare const DETAIL_PRESERVATION_SCHEMA = "Detail preservation. When an observation references specific things, preserve the distinguishing details so future queries can still find them:\n\n- File/location: full path + line number when relevant (src/auth.ts:45, not \"the auth file\").\n- Identifiers and names: package names, function names, variable names, handles, ticket ids, commit SHAs, error codes. Keep them verbatim.\n- Error messages: quote verbatim.\n    BAD:  Build failed with a type error.\n    GOOD: Build failed: TS2322: Type 'string | undefined' is not assignable to type 'string' at src/auth.ts:47.\n- Numerical results: exact values, units, and direction.\n    BAD:  Optimization made it faster.\n    GOOD: Optimization reduced p95 latency from 420ms to 180ms (57% faster).\n- Quantities and counts: \"3 failing tests (auth.test.ts, users.test.ts, routes.test.ts)\" not \"some failing tests\".\n- Recommendation or decision lists: preserve the distinguishing attribute per item.\n    BAD:  Assistant recommended 3 auth libraries.\n    GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid).\n- Role / participation: capture the user's role at an event, not just attendance.\n    BAD:  User worked on the migration.\n    GOOD: User led the migration from MySQL to Postgres.\n\nIf a detail is non-obvious from the code or git history, it belongs in the observation. If it is trivially re-derivable, it does not.";
+export declare const RELEVANCE_RUBRIC = "Relevance levels (pick one per observation; this field drives future pruning):\n\n- critical: user assertions about identity, role, or persistent preferences; explicit corrections (\"no, don't do X\"); concrete completions that future runs MUST NOT redo. These are load-bearing and will NEVER be dropped. Why this matters: if a \"critical\" item is lost, the assistant may redo finished work, contradict a correction, or misrepresent who the user is.\n- high: non-trivial technical decisions, architectural direction, unresolved blockers, key constraints. Worth keeping across many compactions.\n- medium: task-level context that helps within the current work but isn't durable. The default when you are unsure between medium and high.\n- low: routine tool-call acks, repetitive status updates, content trivially re-derivable from recent messages. The pruner will drop these first.\n\nDo NOT default to \"critical\" or \"high\". Most observations are medium or low. Reserve \"critical\" for things that would cause real damage if forgotten.\n\n  BAD:  relevance=critical for \"Agent ran tests and they passed.\"\n  GOOD: relevance=low for \"Agent ran tests and they passed.\" (routine; captured by a completion observation if it matters)\n\n  BAD:  relevance=medium for \"User said they are colorblind; red/green indicators do not work for them.\"\n  GOOD: relevance=critical for \"User said they are colorblind; red/green indicators do not work for them.\" (persistent constraint; forgetting it causes real harm)";
+export declare const OBSERVER_SYSTEM = "You are the observation agent for a coding assistant.\n\nThese records are the ONLY information the assistant will have about past interactions once the raw conversation is compacted out of context. Anything you do not capture here will be forgotten. Anything you distort here will be remembered wrong. Take this seriously.\n\nYour job is to compress a chunk of recent conversation into timestamped, rated observations by calling the record_observations tool. The observations you emit \u2014 together with the reflections crystallized from them \u2014 are the assistant's ONLY memory of this session after the raw conversation falls out of context.\n\nYou receive:\n- Current reflections (long-lived facts already crystallized).\n- Current observations (already-recorded observations, each shown as \"[`id`] YYYY-MM-DD HH:MM [relevance] content\").\n- A new chunk of conversation with source entry labels and inline message timestamps. Each source block starts with \"[Source entry id: <id>]\" followed by content formatted as \"[User @ YYYY-MM-DD HH:MM]:\", \"[Assistant @ ...]:\", \"[Tool result for <name> @ ...]:\", custom messages, or branch summaries.\n- A current local time fallback for observations that have no obvious message timestamp.\n\nHow you work:\n1. Read reflections and current observations so you know what is already captured.\n2. Read the conversation chunk and identify what new information it contains.\n3. Call record_observations with a batch covering part (or all) of the chunk.\n4. Read the progress receipt. If content remains uncovered, call again. You may call the tool many times.\n5. When the chunk is fully covered, STOP calling the tool and reply with a brief plain-text confirmation (one short sentence). That ends the run.\n\nWhat to emit:\n- Produce NEW observations for the new chunk only. Do not restate facts already present in reflections or current observations unless something has materially changed.\n- Use the timestamp from the relevant conversation message. Fall back to current local time ONLY when no message timestamp applies.\n- For every observation, include sourceEntryIds: the smallest exact set of \"[Source entry id: ...]\" ids that directly support the observation.\n- Never invent source entry ids. Use only ids printed in the chunk. If an observation spans multiple turns or tool results, include every supporting source entry id.\n- Observations with missing, empty, or invalid sourceEntryIds will be rejected and not recorded, so do not call record_observations until you can cite valid source ids.\n- Group repeated similar tool calls into a single observation rather than one per call.\n- Skip routine, low-information events. It is fine to emit zero observations if the chunk carries no new information \u2014 in that case, simply do not call the tool and end with a plain-text confirmation.\n\nObservation content rules:\n\nFormat.\n- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.\n- Do NOT include the timestamp or relevance inside the content string \u2014 those are separate fields.\n- No structured fields embedded in the text (no \"key: value\" lines, no JSON).\n\nPreserve user assertions exactly.\nWhen the user TELLS you something about themselves, their project, or their environment, capture it as an assertion. When the user ASKS something, capture it as a question. Assertions are authoritative \u2014 a later question on the same topic does not invalidate them.\n  BAD:  User wondered if they have two kids.\n  GOOD: User stated they have two kids.\n  BAD:  User discussed auth middleware.\n  GOOD: User asked how to configure JWT auth middleware.\nWhy this matters: if the user says \"I use Postgres\" and later asks \"what db am I on?\", downstream agents must treat the assertion as the answer, not the question.\n\nPreserve unusual phrasing.\nWhen the user uses non-standard terminology, quote their exact words so future runs can recognize the term.\n  BAD:  User exercised yesterday.\n  GOOD: User stated they did a \"movement session\" (their term) yesterday.\n\nUse precise action verbs. Replace vague verbs with ones that clarify the nature of the action.\n  BAD:  User got a new subscription.\n  GOOD: User subscribed to the Pro plan.\n  BAD:  User stopped getting the newsletter.\n  GOOD: User unsubscribed from the newsletter.\n  BAD:  User got the library.\n  GOOD: User installed the zod package via pnpm.\n\nFrame state changes as supersession so the old state is explicit.\n  BAD:  User prefers React Query now.\n  GOOD: User will use React Query (switching from SWR).\nWhy this matters: without supersession framing, the reflector may crystallize both the old and the new as equally valid preferences.\n\nMark concrete completions explicitly.\nUse \"completed:\", \"resolved:\", \"confirmed working\", or similar phrasing so future runs know not to redo the work.\n  BAD:  Wrote the login handler.\n  GOOD: completed: implemented login handler at src/auth/login.ts; user confirmed tests pass.\nWhy this matters: without a completion marker, a later assistant may re-implement work that is already done, wasting the user's time and risking regressions.\n\nSplit compound statements into separate observations.\nIf a single message contains multiple independent facts, intents, or events, emit one observation per fact. One observation per line is what enables downstream retrieval and pruning to operate at fact granularity.\n  BAD:  User will visit their parents this weekend and needs to clean the garage.\n  GOOD: User will visit their parents this weekend. + User stated they need to clean the garage this weekend.\n  BAD:  User started a new job and is moving to a new apartment next week.\n  GOOD: User started a new job. + User will move to a new apartment next week.\n  BAD:  Assistant recommended Lucia, NextAuth, and Clerk for auth, and user chose Lucia.\n  GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid). + User chose Lucia.\nWhy this matters: a future query like \"which auth library did the user pick?\" can match a single-fact observation cleanly; a compound observation hides the decision inside a recommendation list.\n\nGroup repeated similar tool calls into a single observation rather than one per call.\n  BAD:  Agent viewed src/auth.ts. Agent viewed src/users.ts. Agent viewed src/routes.ts.\n  GOOD: Agent surveyed auth-related files (src/auth.ts, src/users.ts, src/routes.ts) and located token validation in src/auth.ts:45.\n\nDetail preservation. When an observation references specific things, preserve the distinguishing details so future queries can still find them:\n\n- File/location: full path + line number when relevant (src/auth.ts:45, not \"the auth file\").\n- Identifiers and names: package names, function names, variable names, handles, ticket ids, commit SHAs, error codes. Keep them verbatim.\n- Error messages: quote verbatim.\n    BAD:  Build failed with a type error.\n    GOOD: Build failed: TS2322: Type 'string | undefined' is not assignable to type 'string' at src/auth.ts:47.\n- Numerical results: exact values, units, and direction.\n    BAD:  Optimization made it faster.\n    GOOD: Optimization reduced p95 latency from 420ms to 180ms (57% faster).\n- Quantities and counts: \"3 failing tests (auth.test.ts, users.test.ts, routes.test.ts)\" not \"some failing tests\".\n- Recommendation or decision lists: preserve the distinguishing attribute per item.\n    BAD:  Assistant recommended 3 auth libraries.\n    GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid).\n- Role / participation: capture the user's role at an event, not just attendance.\n    BAD:  User worked on the migration.\n    GOOD: User led the migration from MySQL to Postgres.\n\nIf a detail is non-obvious from the code or git history, it belongs in the observation. If it is trivially re-derivable, it does not.\n\nRelevance levels (pick one per observation; this field drives future pruning):\n\n- critical: user assertions about identity, role, or persistent preferences; explicit corrections (\"no, don't do X\"); concrete completions that future runs MUST NOT redo. These are load-bearing and will NEVER be dropped. Why this matters: if a \"critical\" item is lost, the assistant may redo finished work, contradict a correction, or misrepresent who the user is.\n- high: non-trivial technical decisions, architectural direction, unresolved blockers, key constraints. Worth keeping across many compactions.\n- medium: task-level context that helps within the current work but isn't durable. The default when you are unsure between medium and high.\n- low: routine tool-call acks, repetitive status updates, content trivially re-derivable from recent messages. The pruner will drop these first.\n\nDo NOT default to \"critical\" or \"high\". Most observations are medium or low. Reserve \"critical\" for things that would cause real damage if forgotten.\n\n  BAD:  relevance=critical for \"Agent ran tests and they passed.\"\n  GOOD: relevance=low for \"Agent ran tests and they passed.\" (routine; captured by a completion observation if it matters)\n\n  BAD:  relevance=medium for \"User said they are colorblind; red/green indicators do not work for them.\"\n  GOOD: relevance=critical for \"User said they are colorblind; red/green indicators do not work for them.\" (persistent constraint; forgetting it causes real harm)\n\nTimestamp format: \"YYYY-MM-DD HH:MM\" (local time, 24-hour, to the minute). This goes in the timestamp field, not the content.\n\nRemember: these observations are the assistant's ONLY memory of this chunk once the raw messages fall out of context. Make them count.";
+export declare const REFLECTOR_SYSTEM = "You are the reflection agent for a coding assistant.\n\nThese records are the ONLY information the assistant will have about past interactions once the raw conversation is compacted out of context. Anything you do not capture here will be forgotten. Anything you distort here will be remembered wrong. Take this seriously.\n\nYour job is to crystallize stable, long-lived patterns from accumulated observations into reflections by calling the record_reflections tool. Reflections are the most durable layer of memory: once the pruner drops the observations behind them, the reflection is what remains.\n\nYou are operating on records produced by another part of the memory pipeline \u2014 the observer. To understand what you are reading and to produce reflections in the same voice, the observer was given these rules:\n\n<observation-content-rules>\nObservation content rules:\n\nFormat.\n- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.\n- Do NOT include the timestamp or relevance inside the content string \u2014 those are separate fields.\n- No structured fields embedded in the text (no \"key: value\" lines, no JSON).\n\nPreserve user assertions exactly.\nWhen the user TELLS you something about themselves, their project, or their environment, capture it as an assertion. When the user ASKS something, capture it as a question. Assertions are authoritative \u2014 a later question on the same topic does not invalidate them.\n  BAD:  User wondered if they have two kids.\n  GOOD: User stated they have two kids.\n  BAD:  User discussed auth middleware.\n  GOOD: User asked how to configure JWT auth middleware.\nWhy this matters: if the user says \"I use Postgres\" and later asks \"what db am I on?\", downstream agents must treat the assertion as the answer, not the question.\n\nPreserve unusual phrasing.\nWhen the user uses non-standard terminology, quote their exact words so future runs can recognize the term.\n  BAD:  User exercised yesterday.\n  GOOD: User stated they did a \"movement session\" (their term) yesterday.\n\nUse precise action verbs. Replace vague verbs with ones that clarify the nature of the action.\n  BAD:  User got a new subscription.\n  GOOD: User subscribed to the Pro plan.\n  BAD:  User stopped getting the newsletter.\n  GOOD: User unsubscribed from the newsletter.\n  BAD:  User got the library.\n  GOOD: User installed the zod package via pnpm.\n\nFrame state changes as supersession so the old state is explicit.\n  BAD:  User prefers React Query now.\n  GOOD: User will use React Query (switching from SWR).\nWhy this matters: without supersession framing, the reflector may crystallize both the old and the new as equally valid preferences.\n\nMark concrete completions explicitly.\nUse \"completed:\", \"resolved:\", \"confirmed working\", or similar phrasing so future runs know not to redo the work.\n  BAD:  Wrote the login handler.\n  GOOD: completed: implemented login handler at src/auth/login.ts; user confirmed tests pass.\nWhy this matters: without a completion marker, a later assistant may re-implement work that is already done, wasting the user's time and risking regressions.\n\nSplit compound statements into separate observations.\nIf a single message contains multiple independent facts, intents, or events, emit one observation per fact. One observation per line is what enables downstream retrieval and pruning to operate at fact granularity.\n  BAD:  User will visit their parents this weekend and needs to clean the garage.\n  GOOD: User will visit their parents this weekend. + User stated they need to clean the garage this weekend.\n  BAD:  User started a new job and is moving to a new apartment next week.\n  GOOD: User started a new job. + User will move to a new apartment next week.\n  BAD:  Assistant recommended Lucia, NextAuth, and Clerk for auth, and user chose Lucia.\n  GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid). + User chose Lucia.\nWhy this matters: a future query like \"which auth library did the user pick?\" can match a single-fact observation cleanly; a compound observation hides the decision inside a recommendation list.\n\nGroup repeated similar tool calls into a single observation rather than one per call.\n  BAD:  Agent viewed src/auth.ts. Agent viewed src/users.ts. Agent viewed src/routes.ts.\n  GOOD: Agent surveyed auth-related files (src/auth.ts, src/users.ts, src/routes.ts) and located token validation in src/auth.ts:45.\n</observation-content-rules>\n\n<relevance-rubric>\nRelevance levels (pick one per observation; this field drives future pruning):\n\n- critical: user assertions about identity, role, or persistent preferences; explicit corrections (\"no, don't do X\"); concrete completions that future runs MUST NOT redo. These are load-bearing and will NEVER be dropped. Why this matters: if a \"critical\" item is lost, the assistant may redo finished work, contradict a correction, or misrepresent who the user is.\n- high: non-trivial technical decisions, architectural direction, unresolved blockers, key constraints. Worth keeping across many compactions.\n- medium: task-level context that helps within the current work but isn't durable. The default when you are unsure between medium and high.\n- low: routine tool-call acks, repetitive status updates, content trivially re-derivable from recent messages. The pruner will drop these first.\n\nDo NOT default to \"critical\" or \"high\". Most observations are medium or low. Reserve \"critical\" for things that would cause real damage if forgotten.\n\n  BAD:  relevance=critical for \"Agent ran tests and they passed.\"\n  GOOD: relevance=low for \"Agent ran tests and they passed.\" (routine; captured by a completion observation if it matters)\n\n  BAD:  relevance=medium for \"User said they are colorblind; red/green indicators do not work for them.\"\n  GOOD: relevance=critical for \"User said they are colorblind; red/green indicators do not work for them.\" (persistent constraint; forgetting it causes real harm)\n</relevance-rubric>\n\nYour task is different from the observer's: you are not recording events, you are distilling stable patterns from them.\n\nYou receive:\n- Current reflections (already-crystallized long-lived facts, one per line). Newer reflections may begin with a bracketed id handle; treat that id as recall metadata, not as part of the reflection prose.\n- Current observations (timestamped, relevance-tagged events accumulated over many turns). Each is shown as \"[`id`] YYYY-MM-DD HH:MM [relevance] content\".\n\nHow you work:\n1. Read current reflections and observations to understand what is already crystallized and what new signal exists in the pool.\n2. Identify stable patterns or durable facts worth crystallizing and call record_reflections with a batch of one or more reflection proposals. Each proposal must include the reflection content and supporting observation ids for observations whose durable meaning is captured by that reflection.\n3. Read the receipt. If more reflections are warranted, call record_reflections again with another batch. You may call the tool many times.\n4. When nothing more is stable enough to crystallize, STOP calling the tool and reply with a brief plain-text confirmation (one short sentence). That ends the run.\n\nWhat to emit:\n- Produce new reflections when durable meaning is missing from the current reflections.\n- To strengthen an existing reflection, emit the exact same reflection content with additional supportingObservationIds; the system will merge the supporting ids into the existing reflection.\n- To promote a legacy/no-provenance reflection, emit the exact same reflection content with valid supportingObservationIds; the system will replace it with a provenance-backed reflection.\n- When repeating exact existing content, emit only the reflection prose; omit any bracketed id handle.\n- Do not lightly reword existing reflections. Rewording creates a separate reflection, so only use different wording when the durable meaning is materially different, more specific, or corrects/refines the existing reflection.\n- For every reflection proposal, include supportingObservationIds for current observations whose durable meaning is captured by the reflection and can be treated as redundant active-memory detail. This is a coverage/provenance set, not merely the smallest proof example set.\n- Include additional current observation ids when the reflection preserves their durable meaning with equivalent fidelity. Do not include observations whose unique exact detail, current task state, user correction, user constraint, or concrete completion is not captured by the reflection.\n- Never invent supporting observation ids. Use only ids printed in the current observations list. Reflection proposals with missing, empty, or invalid supportingObservationIds will be rejected and not recorded.\n- Crystallize preferentially from \"high\" and \"critical\" observations, then old \"medium\" observations whose durable meaning can be covered; ignore \"low\" unless a pattern across many \"low\" observations is itself significant.\n- Focus on:\n  - User identity, role, preferences, constraints.\n  - Project goals, architectural decisions, key technical decisions and their rationale.\n  - Recurring user behavior or working style.\n  - Permanent constraints and requirements.\n- It is fine to emit zero reflections if nothing new is stable enough to crystallize \u2014 in that case, simply do not call the tool and end with a plain-text confirmation.\n\nUser assertions are authoritative. If the observation pool contains both \"User stated they use Postgres\" and a later \"User asked which db they are on\", the assertion answers the question \u2014 crystallize the assertion, never the question, as the durable fact.\n\nReflection content rules:\n- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.\n- No timestamp, no priority marker, no [tags], no \"key: value\" fields, no JSON.\n- Preserve user assertions exactly. Use the user's exact words when non-standard.\n- Lead with the fact or pattern; include the reason or mechanism when known so future readers can judge edge cases.\n\n  BAD:  - \uD83D\uDD34 User prefers X\n  BAD:  priority=high User prefers X\n  BAD:  User prefers things.\n  GOOD: User prefers terse responses with no trailing summaries; reason: can read the diff themselves.\n\nRemember: reflections are the layer of memory that survives pruning. If a durable fact never makes it into a reflection, it will eventually be lost.";
+export declare const PRUNER_SYSTEM = "You are the pruning agent for a coding assistant.\n\nThese records are the ONLY information the assistant will have about past interactions once the raw conversation is compacted out of context. Anything you do not capture here will be forgotten. Anything you distort here will be remembered wrong. Take this seriously.\n\nYour job is to aggressively remove observations that are no longer worth keeping by calling the drop_observations tool with their ids. The observation pool must fit under a token budget; the user message tells you how much still needs to be cut, which pass you are on, and the strategy for this pass.\n\nYou are operating on records produced by the observer. To judge what is safe to drop, you must understand how they were created and what each relevance level means:\n\n<observation-content-rules>\nObservation content rules:\n\nFormat.\n- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.\n- Do NOT include the timestamp or relevance inside the content string \u2014 those are separate fields.\n- No structured fields embedded in the text (no \"key: value\" lines, no JSON).\n\nPreserve user assertions exactly.\nWhen the user TELLS you something about themselves, their project, or their environment, capture it as an assertion. When the user ASKS something, capture it as a question. Assertions are authoritative \u2014 a later question on the same topic does not invalidate them.\n  BAD:  User wondered if they have two kids.\n  GOOD: User stated they have two kids.\n  BAD:  User discussed auth middleware.\n  GOOD: User asked how to configure JWT auth middleware.\nWhy this matters: if the user says \"I use Postgres\" and later asks \"what db am I on?\", downstream agents must treat the assertion as the answer, not the question.\n\nPreserve unusual phrasing.\nWhen the user uses non-standard terminology, quote their exact words so future runs can recognize the term.\n  BAD:  User exercised yesterday.\n  GOOD: User stated they did a \"movement session\" (their term) yesterday.\n\nUse precise action verbs. Replace vague verbs with ones that clarify the nature of the action.\n  BAD:  User got a new subscription.\n  GOOD: User subscribed to the Pro plan.\n  BAD:  User stopped getting the newsletter.\n  GOOD: User unsubscribed from the newsletter.\n  BAD:  User got the library.\n  GOOD: User installed the zod package via pnpm.\n\nFrame state changes as supersession so the old state is explicit.\n  BAD:  User prefers React Query now.\n  GOOD: User will use React Query (switching from SWR).\nWhy this matters: without supersession framing, the reflector may crystallize both the old and the new as equally valid preferences.\n\nMark concrete completions explicitly.\nUse \"completed:\", \"resolved:\", \"confirmed working\", or similar phrasing so future runs know not to redo the work.\n  BAD:  Wrote the login handler.\n  GOOD: completed: implemented login handler at src/auth/login.ts; user confirmed tests pass.\nWhy this matters: without a completion marker, a later assistant may re-implement work that is already done, wasting the user's time and risking regressions.\n\nSplit compound statements into separate observations.\nIf a single message contains multiple independent facts, intents, or events, emit one observation per fact. One observation per line is what enables downstream retrieval and pruning to operate at fact granularity.\n  BAD:  User will visit their parents this weekend and needs to clean the garage.\n  GOOD: User will visit their parents this weekend. + User stated they need to clean the garage this weekend.\n  BAD:  User started a new job and is moving to a new apartment next week.\n  GOOD: User started a new job. + User will move to a new apartment next week.\n  BAD:  Assistant recommended Lucia, NextAuth, and Clerk for auth, and user chose Lucia.\n  GOOD: Assistant recommended auth libraries: Lucia (session-based, minimal), NextAuth (OAuth-heavy, Next-native), Clerk (hosted, paid). + User chose Lucia.\nWhy this matters: a future query like \"which auth library did the user pick?\" can match a single-fact observation cleanly; a compound observation hides the decision inside a recommendation list.\n\nGroup repeated similar tool calls into a single observation rather than one per call.\n  BAD:  Agent viewed src/auth.ts. Agent viewed src/users.ts. Agent viewed src/routes.ts.\n  GOOD: Agent surveyed auth-related files (src/auth.ts, src/users.ts, src/routes.ts) and located token validation in src/auth.ts:45.\n</observation-content-rules>\n\n<relevance-rubric>\nRelevance levels (pick one per observation; this field drives future pruning):\n\n- critical: user assertions about identity, role, or persistent preferences; explicit corrections (\"no, don't do X\"); concrete completions that future runs MUST NOT redo. These are load-bearing and will NEVER be dropped. Why this matters: if a \"critical\" item is lost, the assistant may redo finished work, contradict a correction, or misrepresent who the user is.\n- high: non-trivial technical decisions, architectural direction, unresolved blockers, key constraints. Worth keeping across many compactions.\n- medium: task-level context that helps within the current work but isn't durable. The default when you are unsure between medium and high.\n- low: routine tool-call acks, repetitive status updates, content trivially re-derivable from recent messages. The pruner will drop these first.\n\nDo NOT default to \"critical\" or \"high\". Most observations are medium or low. Reserve \"critical\" for things that would cause real damage if forgotten.\n\n  BAD:  relevance=critical for \"Agent ran tests and they passed.\"\n  GOOD: relevance=low for \"Agent ran tests and they passed.\" (routine; captured by a completion observation if it matters)\n\n  BAD:  relevance=medium for \"User said they are colorblind; red/green indicators do not work for them.\"\n  GOOD: relevance=critical for \"User said they are colorblind; red/green indicators do not work for them.\" (persistent constraint; forgetting it causes real harm)\n</relevance-rubric>\n\nYou receive:\n- Current reflections (long-lived facts; they survive regardless \u2014 treat them as already captured). Newer reflections may begin with a bracketed id handle; treat that id as recall metadata, not as part of the reflection prose.\n- Current observations (timestamped, relevance-tagged events to prune). Each is shown as \"[`id`] YYYY-MM-DD HH:MM [relevance] [coverage: tag] content\", where id is the 12-character hex handle you reference when dropping.\n- A pressure line stating pool size, target, tokens still to cut, and the current pass strategy.\n\nCoverage tags are pruning signals derived from current provenance-backed reflection support ids. They are strong evidence, not blind commands:\n- [coverage: uncited] means no current provenance-backed reflection cites this observation. Prune cautiously, especially for medium/high/critical observations, because durable meaning may not be captured elsewhere.\n- [coverage: cited] means 1-3 current provenance-backed reflections cite this observation. Once it is old, it is a strong pruning candidate for low/medium observations when the reflection preserves equivalent meaning. Old high observations can also be dropped when the reflection captures the same fact, unless they carry current task state or exact details not captured with equivalent fidelity.\n- [coverage: reinforced] means 4 or more current provenance-backed reflections cite this observation. Once it is old, it is a presumptive drop candidate because durable meaning is likely represented. Still preserve it if it carries current/recent task state, exact errors, file paths, commands, identifiers, user assertions, constraints, corrections, concrete completions, or nuance not captured with equivalent fidelity.\n\nActive-memory framing. Dropping an observation removes it from active compacted memory; it does not necessarily erase all evidence. When an observation is [coverage: cited] or [coverage: reinforced], a current source-backed reflection preserves a provenance path to that observation and its raw sources, so exact evidence can still be recovered later through recall of the reflection id. Use that provenance as permission to prune old redundant active-memory detail. However, uncited observations, unique current task state, and protected details not captured by a reflection with equivalent fidelity may become effectively unavailable in the compacted summary, so preserve them.\n\nHow you work:\n1. Read reflections and the observation pool.\n2. Identify ids that should be removed and call drop_observations with them. Pass multiple ids per call and call the tool multiple times as you work the pool down toward the target.\n3. Read the receipt after each call to see what was dropped and how many remain.\n4. When no further sound drops are possible, STOP calling the tool and reply with a brief plain-text confirmation. That ends the run.\n\nThis agent may be invoked again in a follow-up pass if the pool is still over budget \u2014 focus each run on your next-weakest drops rather than trying to do everything in one call.\n\nWhat to drop (in priority order):\n- Signal-captured: observations tagged [coverage: reinforced] or [coverage: cited] whose durable meaning is captured by a reflection now in the reflections list. Old reinforced observations should usually be dropped unless they uniquely carry protected details. Old cited low/medium observations are strong drop candidates. Old cited high observations may be dropped when the reflection captures the same fact, but keep them when they contain current/recent task state, exact errors, file paths, commands, identifiers, user assertions, constraints, corrections, concrete completions, or nuance not captured with equivalent fidelity.\n- Superseded: directly contradicted or replaced by a newer observation.\n- Redundant: near-duplicate of another observation (keep the higher-relevance or more recent one).\n- Exhausted routine: tool-call acks, status updates, trivia that no longer affects the work.\n\nAge-gradient rule. Recent observations carry working context the assistant still needs; older observations have usually been summarized elsewhere or are no longer load-bearing. When choosing between two equally droppable items, drop the older one first. For \"low\" and \"medium\" observations, compress older history more aggressively than recent turns.\n\n  BAD:  drop the most recent \"low\" observation because \"low\" is easiest to justify.\n  GOOD: drop the oldest \"low\" observations; keep recent \"low\" observations until budget pressure forces otherwise.\n\nRelevance guidance:\n- \"low\": drop freely once reviewed. Why: these were marked low because they add little signal; keeping them crowds out more useful records.\n- \"medium\": drop when redundant with reflections or other observations, especially when [coverage: cited] or [coverage: reinforced], or when the task context has moved on.\n- \"high\": drop when clearly superseded or already captured by a reflection; for old [coverage: cited] or [coverage: reinforced] high observations, require only that the reflection captures the same durable fact and no protected exact detail is unique to the observation.\n- \"critical\": NEVER drop. These encode user identity, explicit corrections, and concrete completions. Why this matters: dropping a critical item causes the assistant to repeat finished work, contradict an explicit correction, or misrepresent who the user is. No amount of budget pressure justifies this.\n\nUser assertions and concrete completions are never droppable, even at non-critical relevance. If the relevance was mis-labeled but the content is load-bearing (an assertion about the user or a marker that work is done), treat the content as authoritative and skip the drop.\n\n  BAD:  drop \"[id] 2025-12-04 14:30 [low] User stated they are colorblind\" because it is marked low.\n  GOOD: keep that observation; the content is a user assertion about a persistent constraint, and relevance is mis-labeled.\n\nPreservation floor. Regardless of relevance label or age, do not drop observations that uniquely carry any of the following \u2014 they are not re-derivable once gone:\n\n- Named identifiers appearing nowhere else in the kept set: package names, file paths, function/variable names, ticket ids, commit SHAs, handles, error codes.\n- Dates of specific events (release cuts, deadlines, meetings, incidents).\n- Error messages captured verbatim, especially ones the user hit.\n- Architectural or technical decisions and their rationale (the \"why\" behind the choice, not just the choice).\n- User preferences, constraints, and corrections \u2014 even when phrased without the word \"prefer\".\n\nIf one of these categories is ALSO captured by an existing reflection with equivalent fidelity, the observation becomes redundant and is droppable. Otherwise, keep it even under budget pressure.\n\n  BAD:  drop \"[id] 2025-12-04 14:30 [medium] Build failed: TS2322 at src/auth.ts:47 \u2014 Type 'string | undefined' is not assignable to type 'string'\" because it is only medium and the task moved on.\n  GOOD: keep that observation; it is a verbatim error the user hit, not captured in any reflection. Future debugging may need the exact code and location.\n\nWhen in doubt, prefer dropping reinforced observations first, then cited observations, before uncited observations. Coverage tags are strong signals, not blind commands: reflections protect durable facts only when they preserve equivalent meaning. The only things you must preserve unconditionally are critical observations, user assertions, and concrete completions.\n\nWhat you CANNOT do:\n- You cannot merge observations. If two overlap, drop the weaker one.\n- You cannot rewrite or edit observations. The kept set preserves content, timestamp, and relevance exactly as they were.\n- You cannot add new observations.\n\nIt is valid to end a pass with zero drops if the pool genuinely has nothing more to cut \u2014 a follow-up pass will be skipped when a run returns zero drops. On late pressure passes, first re-check old [coverage: reinforced] and [coverage: cited] observations as active-memory redundancies before deciding there are no sound drops. Do not force drops you don't believe in.\n\nRemember: pruning is active-memory management, not source deletion. A drop that looks reasonable at \"low\" still becomes a mistake if the content was a user correction with a mis-labeled relevance and no reflection captures it with equivalent fidelity. Read before you cut.";
+export declare function buildReflectorPassGuidance(pass: number, maxPasses: number): string;
+export declare function buildPrunerPassGuidance(pass: number, maxPasses: number): string;
+export declare const CONTEXT_USAGE_INSTRUCTIONS = "These are condensed memories from earlier in this session.\n\n- Reflections: stable, long-lived facts about the user, project, decisions, and constraints. New reflection lines may include ids in brackets wrapped in backticks.\n- Observations: timestamped events from the conversation history, in chronological order. Observation lines include ids in brackets wrapped in backticks.\n\nTreat these as past records. When entries conflict, the most recent observation reflects the latest known state. Work that prior observations describe as completed should not be redone unless the user explicitly asks to revisit it.\n\nWhen exact source context is needed for precision or traceability, use the recall tool with the relevant observation or reflection id. This is especially useful when a reflection materially affects a decision or is too compressed to continue confidently. Do not use recall as broad search or inject raw source unless it is needed.";
+//# sourceMappingURL=prompts.d.ts.map

package/dist/memory/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/memory/prompts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,+QAA+Q,CAAC;AAE1S,eAAO,MAAM,yBAAyB,6oHAmD+F,CAAC;AAEtI,eAAO,MAAM,0BAA0B,67CAkB+F,CAAC;AAEvI,eAAO,MAAM,gBAAgB,8+CAasI,CAAC;AAEpK,eAAO,MAAM,eAAe,knTAoC2G,CAAC;AAExI,eAAO,MAAM,gBAAgB,69UA0DwH,CAAC;AAEtJ,eAAO,MAAM,aAAa,u2cAgFuP,CAAC;AASlR,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGlF;AASD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG/E;AAED,eAAO,MAAM,0BAA0B,07BAOoS,CAAC"}

package/dist/memory/relevance.d.ts

@@ -0,0 +1,4 @@
+import { type ObservationRecord, type Relevance } from "./types.js";
+export declare function countByRelevance(records: ObservationRecord[]): Record<Relevance, number>;
+export declare function formatRelevanceHistogram(counts: Record<Relevance, number>): string;
+//# sourceMappingURL=relevance.d.ts.map

package/dist/memory/relevance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relevance.d.ts","sourceRoot":"","sources":["../../src/memory/relevance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,SAAS,EAAoB,MAAM,YAAY,CAAC;AAEtF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAIxF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,GAAG,MAAM,CAMlF"}

package/dist/memory/runtime.d.ts

@@ -0,0 +1,40 @@
+import { type Config } from "./config.js";
+export type ResolveResult = {
+    ok: true;
+    model: unknown;
+    apiKey: string;
+    headers?: Record<string, string>;
+} | {
+    ok: false;
+    reason: string;
+};
+type NotifyLevel = "warning" | "info" | "error";
+type Notify = (message: string, type?: NotifyLevel) => void;
+export interface ResolveCtx {
+    model: unknown;
+    modelRegistry: any;
+    hasUI: boolean;
+    ui?: {
+        notify: Notify;
+    };
+}
+export interface LaunchCtx {
+    hasUI: boolean;
+    ui?: {
+        notify: Notify;
+    };
+}
+export declare class Runtime {
+    config: Config;
+    configLoaded: boolean;
+    observerInFlight: boolean;
+    observerPromise: Promise<void> | null;
+    compactInFlight: boolean;
+    compactHookInFlight: boolean;
+    resolveFailureNotified: boolean;
+    ensureConfig(cwd: string): void;
+    resolveModel(ctx: ResolveCtx): Promise<ResolveResult>;
+    launchObserverTask(ctx: LaunchCtx, label: string, work: () => Promise<void>): Promise<void>;
+}
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/dist/memory/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/memory/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAwB,MAAM,aAAa,CAAC;AAEhE,MAAM,MAAM,aAAa,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC9E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC,KAAK,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAChD,KAAK,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,IAAI,CAAC;AAE5D,MAAM,WAAW,UAAU;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,GAAG,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACxB;AAED,qBAAa,OAAO;IACnB,MAAM,EAAE,MAAM,CAAmB;IACjC,YAAY,UAAS;IACrB,gBAAgB,UAAS;IACzB,eAAe,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAQ;IAC7C,eAAe,UAAS;IACxB,mBAAmB,UAAS;IAC5B,sBAAsB,UAAS;IAE/B,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMzB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAsB3D,kBAAkB,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAsB3F"}

package/dist/memory/serialize.d.ts

@@ -0,0 +1,26 @@
+import type { Message } from "../sdk/ai/index.js";
+export declare function serializeConversation(messages: Message[]): string;
+export declare function nowTimestamp(): string;
+export declare const MAX_RECORD_CONTENT_CHARS = 10000;
+export declare function truncateRecordContent(content: string): string;
+export type RenderableEntry = {
+    type: string;
+    id?: string;
+    timestamp?: string;
+    message?: unknown;
+    customType?: string;
+    content?: unknown;
+    summary?: unknown;
+};
+export declare function serializeBranchEntries(entries: RenderableEntry[]): string;
+export type SourceAddressedSerialization = {
+    text: string;
+    sourceEntryIds: string[];
+};
+export declare const DURABLE_SOURCE_ENTRY_ID_PREFIX = "srcv1:";
+export declare function durableSourceEntryId(entry: RenderableEntry): string | undefined;
+export declare function sourceEntryReferenceIds(entry: RenderableEntry): string[];
+export declare function serializeSourceAddressedBranchEntries(entries: RenderableEntry[]): SourceAddressedSerialization;
+export declare function renderRecallSourceEntry(entry: RenderableEntry): string | null;
+export declare function renderRecallSourceEntries(entries: RenderableEntry[]): string;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/memory/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/memory/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAkC,MAAM,oBAAoB,CAAC;AAuElF,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,MAAM,CAwBjE;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,MAAM,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAsBF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBzE;AAED,MAAM,MAAM,4BAA4B,GAAG;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF,eAAO,MAAM,8BAA8B,WAAW,CAAC;AAevD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAY/E;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE,CAMxE;AAED,wBAAgB,qCAAqC,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,4BAA4B,CAY9G;AAuBD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAQ7E;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAK5E"}

package/dist/memory/tokens.d.ts

@@ -0,0 +1,8 @@
+export declare function estimateStringTokens(text: string): number;
+export declare function estimateEntryTokens(entry: {
+    type: string;
+    message?: unknown;
+    content?: unknown;
+    summary?: unknown;
+}): number;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/memory/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/memory/tokens.ts"],"names":[],"mappings":"AAEA,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAmB5H"}

package/dist/memory/tools/read-project-observations.d.ts

@@ -0,0 +1,8 @@
+import { Type } from "../../sdk/ai/index.js";
+import { type ExtensionAPI } from "../../sdk/coding-agent/index.js";
+export declare const READ_PROJECT_OBSERVATIONS_TOOL_NAME = "read_project_observations";
+export declare const readProjectObservationsTool: import("../../sdk/coding-agent/index.js").ToolDefinition<Type.TObject<{
+    query: Type.TString;
+}>, unknown> & import("../../sdk/coding-agent/index.js").ToolDefinition<any, any>;
+export declare function registerReadProjectObservationsTool(pi: ExtensionAPI): void;
+//# sourceMappingURL=read-project-observations.d.ts.map

package/dist/memory/tools/read-project-observations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-project-observations.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/read-project-observations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAGhF,eAAO,MAAM,mCAAmC,8BAA8B,CAAC;AAE/E,eAAO,MAAM,2BAA2B;;iFAqFtC,CAAC;AAEH,wBAAgB,mCAAmC,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAE1E"}

package/dist/memory/tools/recall-observation.d.ts

@@ -0,0 +1,63 @@
+import { Type } from "../../sdk/ai/index.js";
+import { type ExtensionAPI } from "../../sdk/coding-agent/index.js";
+import { type RecallMemoryObservation } from "../branch.js";
+import type { ObservationRecord, ReflectionRecord } from "../types.js";
+export declare const RECALL_OBSERVATION_TOOL_NAME = "recall";
+type RecallObservationToolStatus = "ok" | "partial" | "invalid_id" | "not_found" | "no_source" | "source_unavailable" | "no_provenance";
+type ObservationDetails = Pick<ObservationRecord, "id" | "content" | "timestamp" | "relevance">;
+type ReflectionDetails = Pick<ReflectionRecord, "id" | "content" | "supportingObservationIds" | "legacy"> & {
+    reflectionIndex: number;
+};
+export type RecallSourceEntryDetails = {
+    id: string;
+    origin: string;
+    timestamp: string;
+    tokens: number;
+    qualifiers: string[];
+    content?: string;
+};
+type RecallObservationMatchDetails = {
+    status: RecallMemoryObservation["status"];
+    observationEntryId: string;
+    observationRecordIndex: number;
+    observation: ObservationDetails;
+    sourceEntryIds?: string[];
+    sourceEntries?: RecallSourceEntryDetails[];
+    missingSourceEntryIds?: string[];
+    nonSourceEntryIds?: string[];
+    sourceCharacterCount?: number;
+};
+type RecallUnavailableSupportingObservationDetails = {
+    reflectionId: string;
+    reflectionIndex: number;
+    observationId: string;
+};
+type RecallUnavailableReflectionProvenanceDetails = {
+    reflectionId: string;
+    reflectionIndex: number;
+    reason: "legacy";
+};
+export type RecallObservationToolDetails = {
+    status: RecallObservationToolStatus;
+    memoryId: string;
+    observationId: string;
+    collision: boolean;
+    partial: boolean;
+    reflections: ReflectionDetails[];
+    directObservationMatches: RecallObservationMatchDetails[];
+    observations: RecallObservationMatchDetails[];
+    matches: RecallObservationMatchDetails[];
+    sourceEntries: RecallSourceEntryDetails[];
+    unavailableSupportingObservations: RecallUnavailableSupportingObservationDetails[];
+    unavailableReflectionProvenance: RecallUnavailableReflectionProvenanceDetails[];
+    missingSourceEntryIds: string[];
+    nonSourceEntryIds: string[];
+    sourceCharacterCount?: number;
+    message?: string;
+};
+export declare const recallObservationTool: import("../../sdk/coding-agent/index.js").ToolDefinition<Type.TObject<{
+    id: Type.TString;
+}>, unknown> & import("../../sdk/coding-agent/index.js").ToolDefinition<any, any>;
+export declare function registerRecallTool(pi: ExtensionAPI): void;
+export {};
+//# sourceMappingURL=recall-observation.d.ts.map

package/dist/memory/tools/recall-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-observation.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/recall-observation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAE7C,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAEhF,OAAO,EAGN,KAAK,uBAAuB,EAE5B,MAAM,cAAc,CAAC;AAGtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEvE,eAAO,MAAM,4BAA4B,WAAW,CAAC;AAIrD,KAAK,2BAA2B,GAC7B,IAAI,GACJ,SAAS,GACT,YAAY,GACZ,WAAW,GACX,WAAW,GACX,oBAAoB,GACpB,eAAe,CAAC;AAEnB,KAAK,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC;AAChG,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,GAAG,SAAS,GAAG,0BAA0B,GAAG,QAAQ,CAAC,GAAG;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAExI,MAAM,MAAM,wBAAwB,GAAG;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,KAAK,6BAA6B,GAAG;IACpC,MAAM,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC1C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,WAAW,EAAE,kBAAkB,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;IAC3C,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,KAAK,6CAA6C,GAAG;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,KAAK,4CAA4C,GAAG;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,QAAQ,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG;IAC1C,MAAM,EAAE,2BAA2B,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,wBAAwB,EAAE,6BAA6B,EAAE,CAAC;IAC1D,YAAY,EAAE,6BAA6B,EAAE,CAAC;IAC9C,OAAO,EAAE,6BAA6B,EAAE,CAAC;IACzC,aAAa,EAAE,wBAAwB,EAAE,CAAC;IAC1C,iCAAiC,EAAE,6CAA6C,EAAE,CAAC;IACnF,+BAA+B,EAAE,4CAA4C,EAAE,CAAC;IAChF,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAuUF,eAAO,MAAM,qBAAqB;;iFAuChC,CAAC;AAEH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAEzD"}

package/dist/memory/tools/write-project-observation.d.ts

@@ -0,0 +1,9 @@
+import { Type } from "../../sdk/ai/index.js";
+import { type ExtensionAPI } from "../../sdk/coding-agent/index.js";
+export declare const WRITE_PROJECT_OBSERVATION_TOOL_NAME = "write_project_observation";
+export declare const writeProjectObservationTool: import("../../sdk/coding-agent/index.js").ToolDefinition<Type.TObject<{
+    content: Type.TString;
+    relevance: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">, Type.TLiteral<"critical">]>;
+}>, unknown> & import("../../sdk/coding-agent/index.js").ToolDefinition<any, any>;
+export declare function registerWriteProjectObservationTool(pi: ExtensionAPI): void;
+//# sourceMappingURL=write-project-observation.d.ts.map

package/dist/memory/tools/write-project-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-project-observation.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/write-project-observation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAIhF,eAAO,MAAM,mCAAmC,8BAA8B,CAAC;AAE/E,eAAO,MAAM,2BAA2B;;;iFA6DtC,CAAC;AAEH,wBAAgB,mCAAmC,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAE1E"}

package/dist/memory/tools/write-project-observation.js

@@ -0,0 +1,60 @@
+import { Type } from "../../sdk/ai/index.js";
+import { defineTool } from "../../sdk/coding-agent/index.js";
+import { getProjectObsStore } from "../project-observations-store.js";
+import { hashId } from "../ids.js";
+export const WRITE_PROJECT_OBSERVATION_TOOL_NAME = "write_project_observation";
+export const writeProjectObservationTool = defineTool({
+    name: WRITE_PROJECT_OBSERVATION_TOOL_NAME,
+    label: "Write project observation",
+    description: "Write a durable, cross-session observation about this project. " +
+        "Use this to persist discovered conventions, architectural rules, " +
+        "gotchas, and directory purposes. Observations are deduplicated by " +
+        "content hash — writing the same fact twice is harmless (idempotent). " +
+        "Future sessions can discover these via read_project_observations.",
+    promptSnippet: "Use write_project_observation(content, relevance) to persist project-level knowledge.",
+    promptGuidelines: [
+        "Use for STABLE facts: conventions, architecture decisions, gotchas, file roles.",
+        "Use relevance='critical' for NEVER-EDIT rules (auto-generated files, invariant constraints).",
+        "Use relevance='high' for important conventions the agent must follow.",
+        "Use relevance='medium' for useful patterns and directory purposes.",
+        "Content must be a single, self-contained sentence — no markdown, no lists.",
+        "Deduplication is automatic — same content = same ID → INSERT OR REPLACE.",
+    ],
+    parameters: Type.Object({
+        content: Type.String({
+            minLength: 1,
+            description: "A single self-contained sentence describing the fact. No markdown, no lists.",
+        }),
+        relevance: Type.Union([
+            Type.Literal("low"),
+            Type.Literal("medium"),
+            Type.Literal("high"),
+            Type.Literal("critical"),
+        ], { description: "Importance: critical > high > medium > low" }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        const store = getProjectObsStore();
+        if (!store) {
+            return {
+                content: [{ type: "text", text: "Project observations store is not available." }],
+                details: { status: "store_unavailable" },
+            };
+        }
+        const projectId = store.getProjectByCwd(ctx.cwd);
+        if (!projectId) {
+            return {
+                content: [{ type: "text", text: `No project found for current working directory: ${ctx.cwd}` }],
+                details: { status: "no_project" },
+            };
+        }
+        const id = hashId(params.content);
+        store.insertProjectObservations(projectId, "auto-research", [{ id, content: params.content, relevance: params.relevance }], Date.now());
+        return {
+            content: [{ type: "text", text: `Observation [${id}] recorded (relevance: ${params.relevance}).` }],
+            details: { id, status: "ok" },
+        };
+    },
+});
+export function registerWriteProjectObservationTool(pi) {
+    pi.registerTool(writeProjectObservationTool);
+}

package/dist/memory/types.d.ts

@@ -0,0 +1,65 @@
+export declare const OBSERVATION_CUSTOM_TYPE = "om.observation";
+export declare const OBSERVATIONAL_MEMORY_SNAPSHOT_CUSTOM_TYPE = "om.snapshot";
+export declare const OBSERVATIONAL_MEMORY_CONTEXT_CUSTOM_TYPE = "om.snapshot.context";
+export type Relevance = "low" | "medium" | "high" | "critical";
+export declare const RELEVANCE_VALUES: readonly Relevance[];
+export declare const MEMORY_ID_PATTERN: RegExp;
+export interface ObservationRecord {
+    id: string;
+    content: string;
+    timestamp: string;
+    relevance: Relevance;
+    sourceEntryIds?: string[];
+}
+export type LegacyReflection = string;
+export interface ReflectionRecord {
+    id: string;
+    content: string;
+    supportingObservationIds: string[];
+    legacy?: boolean;
+}
+export type MemoryReflection = LegacyReflection | ReflectionRecord;
+/**
+ * Current runtime reflection alias used by pre-v4 consumers. Later producer/consumer
+ * steps should migrate surfaces that need id-bearing records to MemoryReflection.
+ */
+export type Reflection = LegacyReflection;
+export interface MemoryDetailsV3 {
+    type: "observational-memory";
+    version: 3;
+    observations: ObservationRecord[];
+    reflections: LegacyReflection[];
+}
+export interface MemoryDetailsV4 {
+    type: "observational-memory";
+    version: 4;
+    observations: ObservationRecord[];
+    reflections: MemoryReflection[];
+}
+export type SupportedMemoryDetails = MemoryDetailsV3 | MemoryDetailsV4;
+export type MemoryDetails = MemoryDetailsV3;
+export interface ObservationEntryData {
+    records: ObservationRecord[];
+    coversFromId: string;
+    coversUpToId: string;
+    tokenCount: number;
+}
+export interface RestoredMemorySnapshot {
+    type: "observational-memory-snapshot";
+    version: 1;
+    coveredSourceCount: number;
+    summary: string;
+    details: SupportedMemoryDetails;
+}
+export declare function isReflectionRecord(v: unknown): v is ReflectionRecord;
+export declare function isMemoryReflection(v: unknown): v is MemoryReflection;
+export declare function reflectionContent(reflection: MemoryReflection): string;
+export declare function reflectionId(reflection: MemoryReflection): string | undefined;
+export declare function reflectionToPromptLine(reflection: MemoryReflection): string;
+export declare function isMemoryDetailsV3(d: unknown): d is MemoryDetailsV3;
+export declare function isMemoryDetailsV4(d: unknown): d is MemoryDetailsV4;
+export declare function isSupportedMemoryDetails(d: unknown): d is SupportedMemoryDetails;
+export declare function isMemoryDetails(d: unknown): d is MemoryDetails;
+export declare function isObservationEntryData(d: unknown): d is ObservationEntryData;
+export declare function isRestoredMemorySnapshot(d: unknown): d is RestoredMemorySnapshot;
+//# sourceMappingURL=types.d.ts.map

package/dist/memory/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,mBAAmB,CAAC;AACxD,eAAO,MAAM,yCAAyC,gBAAgB,CAAC;AACvE,eAAO,MAAM,wCAAwC,wBAAwB,CAAC;AAE9E,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE/D,eAAO,MAAM,gBAAgB,EAAE,SAAS,SAAS,EAAmD,CAAC;AAErG,eAAO,MAAM,iBAAiB,QAAmB,CAAC;AAElD,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEtC,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAE1C,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,WAAW,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,WAAW,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAED,MAAM,MAAM,sBAAsB,GAAG,eAAe,GAAG,eAAe,CAAC;AAEvE,MAAM,MAAM,aAAa,GAAG,eAAe,CAAC;AAE5C,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,+BAA+B,CAAC;IACtC,OAAO,EAAE,CAAC,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,sBAAsB,CAAC;CAChC;AA6BD,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,gBAAgB,CAepE;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,gBAAgB,CAEpE;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,CAEtE;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAE7E;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,gBAAgB,GAAG,MAAM,CAE3E;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,eAAe,CAOlE;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,eAAe,CAOlE;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,sBAAsB,CAEhF;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,aAAa,CAE9D;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,oBAAoB,CAU5E;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,sBAAsB,CAYhF"}

package/dist/preflight.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared pre-flight check: every authenticated `spectral` subcommand (and the
+ * fall-through to pi) must verify that credentials exist in
+ * `~/.spectral/config.json` before proceeding.
+ *
+ * Extracted from `cli.ts` so `serve` (and any future subcommand) reuses the
+ * exact same UX — message wording, exit code, stderr formatting.
+ *
+ * `requireLogin()` writes to stderr and calls `process.exit(1)` on failure;
+ * `checkLogin()` is the testable variant that just reports the result so we
+ * can assert on it without killing the test runner.
+ */
+import { type SpectralConfig } from "./config.js";
+export interface LoginCheckResult {
+    ok: boolean;
+    config: SpectralConfig | null;
+    /** Path that was inspected. Surfaced so callers can include it in messages. */
+    configFile: string;
+}
+/** Inspect login state without side effects. Safe to call from tests. */
+export declare function checkLogin(): Promise<LoginCheckResult>;
+/**
+ * Enforce login: returns the config on success, prints a friendly error and
+ * exits 1 on failure. Matches the wording used by the main spawn path.
+ */
+export declare function requireLogin(): Promise<SpectralConfig>;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;CACpB;AAUD,yEAAyE;AACzE,wBAAsB,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAG5D;AAED;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,cAAc,CAAC,CAQ5D"}

package/dist/preflight.js

@@ -14,7 +14,9 @@ import { getConfigFile, readConfig } from "./config.js";
 // Plain ANSI red. Mirrors the helper in cli.ts; we intentionally keep this
 // dependency-light so pre-flight stays cheap on cold start.
 function red(s) {
-    return process.stdout.isTTY || process.stderr.isTTY ? `\x1b[31m${s}\x1b[0m` : s;
+    return process.stdout.isTTY || process.stderr.isTTY
+        ? `\x1b[31m${s}\x1b[0m`
+        : s;
 }
 /** Inspect login state without side effects. Safe to call from tests. */
 export async function checkLogin() {

package/dist/relay/auto-research.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Auto-research handler — sends an auto-research task through the existing
+ * AgentBridge (backend proxy) instead of spawning a separate pi process.
+ *
+ * This ensures auto-research uses the same model and API keys as the active
+ * session — no separate subprocess, no missing API key errors.
+ *
+ * Flow:
+ *   1. Build the auto-research task prompt
+ *   2. Ensure session subscriber exists (borrows handleClientMessage pattern)
+ *   3. Emit auto_research_start via relay
+ *   4. Send task via manager.prompt() — goes through backend proxy with session's model
+ *   5. Attach a watcher subscriber to detect turn completion
+ *   6. On agent_end, scan for generated extensions and emit auto_research_complete
+ *   7. On error, emit auto_research_error
+ */
+import type { SessionStore } from "../server/storage.js";
+import type { SessionStreamManager, Subscriber } from "../server/session-stream.js";
+import type { RelayClient } from "./client.js";
+/** Input shape consumed by `handleAutoResearch`. */
+export interface AutoResearchInput {
+    projectId: string;
+    sessionId: string;
+}
+/** Dependencies injected by the dispatcher. */
+export interface AutoResearchDeps {
+    store: SessionStore;
+    manager: SessionStreamManager;
+    relay: Pick<RelayClient, "send">;
+    /** Subscriber map shared with handleClientMessage — ensures the session
+     *  already has a wire subscriber before we prompt. */
+    subscribers: Map<string, Subscriber>;
+    /** Project working directory (cwd from serve.ts). Used for file scanning. */
+    cwd: string;
+    /** Optional logger. Defaults to console.error. */
+    logger?: {
+        error: (...args: unknown[]) => void;
+    };
+}
+/**
+ * An extension discovered or generated by auto-research.
+ * Mirrors the shape in `ServerEvent["auto_research_complete"]["extensions"]`.
+ */
+export interface AutoResearchExtension {
+    name: string;
+    path: string;
+    description: string;
+    usesLLM?: boolean;
+    fileCount?: number;
+}
+/**
+ * Execute auto-research for a project through the existing AgentBridge.
+ *
+ * Caller (dispatcher) is fire-and-forget — this function is `void` and
+ * all errors are surfaced as `auto_research_error` events on the wire
+ * rather than thrown.
+ *
+ * This replaces the old subprocess-spawning approach. Instead of launching
+ * a separate pi process (which lacks backend proxy credentials), we send
+ * the auto-research task through the session's existing AgentBridge. The agent
+ * uses the session's model, backend proxy, and all available tools.
+ */
+export declare function handleAutoResearch(input: AutoResearchInput, deps: AutoResearchDeps): void;
+//# sourceMappingURL=auto-research.d.ts.map

package/dist/relay/auto-research.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-research.d.ts","sourceRoot":"","sources":["../../src/relay/auto-research.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAEpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM/C,oDAAoD;AACpD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACjC;0DACsD;IACtD,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAksBD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,gBAAgB,GACrB,IAAI,CAmLN"}