@lota-sdk/core 0.1.5

package/src/storage/generated-document-storage.service.ts

@@ -0,0 +1,55 @@
+import { S3Client } from 'bun'
+
+import { env } from '../config/env-shapes'
+
+function toSafeSegment(value: string): string {
+  return value
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/\.\.+/g, '.')
+    .replace(/[^a-zA-Z0-9._/-]+/g, '-')
+}
+
+function buildGeneratedDocumentStorageKey(params: {
+  organizationId: string
+  namespace: string
+  relativePath: string
+}): string {
+  const safeOrganizationId = toSafeSegment(params.organizationId)
+  const safeNamespace = toSafeSegment(params.namespace)
+  const safeRelativePath = toSafeSegment(params.relativePath)
+  return `${safeOrganizationId}/generated/${safeNamespace}/${safeRelativePath}`
+}
+
+class GeneratedDocumentStorageService {
+  private _client: InstanceType<typeof S3Client> | undefined
+
+  private get client(): InstanceType<typeof S3Client> {
+    if (!this._client) {
+      this._client = new S3Client({
+        accessKeyId: env.S3_ACCESS_KEY_ID,
+        secretAccessKey: env.S3_SECRET_ACCESS_KEY,
+        bucket: env.S3_BUCKET,
+        endpoint: env.S3_ENDPOINT,
+        region: env.S3_REGION,
+      })
+    }
+    return this._client
+  }
+
+  async writeTextArtifact(params: {
+    organizationId: string
+    namespace: string
+    relativePath: string
+    content: string
+    mediaType: string
+  }): Promise<{ storageKey: string; sizeBytes: number }> {
+    const storageKey = buildGeneratedDocumentStorageKey(params)
+    const sizeBytes = Buffer.byteLength(params.content, 'utf8')
+    await this.client.file(storageKey).write(params.content, { type: params.mediaType })
+    return { storageKey, sizeBytes }
+  }
+}
+
+export const generatedDocumentStorageService = new GeneratedDocumentStorageService()

package/src/system-agents/agent-result.ts

@@ -0,0 +1,27 @@
+const SUBSTANTIVE_CHAR_PATTERN = /[\p{L}\p{N}]/u
+const WORD_LIKE_PATTERN = /[\p{L}\p{N}][\p{L}\p{N}/._'-]*/gu
+
+function normalizeAgentResultText(value: string): string {
+  return value.replaceAll(String.fromCharCode(0), '').replace(/\r/g, '').trim()
+}
+
+function isSubstantiveAgentResult(value: string): boolean {
+  const normalized = normalizeAgentResultText(value)
+  if (!normalized || !SUBSTANTIVE_CHAR_PATTERN.test(normalized)) {
+    return false
+  }
+
+  const wordLikeParts = normalized.match(WORD_LIKE_PATTERN) ?? []
+  const alphaNumericCount = Array.from(normalized.matchAll(/[\p{L}\p{N}]/gu)).length
+
+  return alphaNumericCount >= 4 && (normalized.length >= 8 || wordLikeParts.length >= 2)
+}
+
+export function assertSubstantiveAgentResult(value: string, label = 'Agent result'): string {
+  const normalized = normalizeAgentResultText(value)
+  if (!isSubstantiveAgentResult(normalized)) {
+    throw new Error(`${label} must contain substantive text.`)
+  }
+
+  return normalized
+}

package/src/system-agents/context-compacter.agent.ts

@@ -0,0 +1,46 @@
+import { ToolLoopAgent } from 'ai'
+
+import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import {
+  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
+  OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+} from '../config/model-constants'
+import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+import { resolveHelperAgentOptions } from './helper-agent-options'
+
+const contextCompacterPrompt = `<agent-instructions>
+You are a **Context Compacter** that produces both:
+1) a dense but shorter summary of prior context
+2) a structured state delta for durable execution continuity
+
+<task>
+Compress historical context while preserving execution-critical details.
+When provided with existing state, update only changed fields.
+</task>
+
+<rules>
+- Preserve concrete decisions, constraints, assumptions, plans, open questions, and unresolved risks.
+- Preserve action ownership, specialist consultations, and the latest working direction.
+- Preserve provenance by attaching \`sourceMessageIds\` only from the provided message IDs.
+- Keep identifiers, numbers, dates, and proper nouns when present.
+- Remove filler and repetition.
+- Do not invent details.
+- If uncertain, prefer an empty array or null over guessing.
+</rules>
+
+<output-format>
+The caller enforces a structured output schema.
+Return valid data for:
+- summary: concise text summary
+- stateDelta: include every field; use empty arrays for unchanged list fields, null for unchanged nullable fields, and \`currentPlan.action\` to signal \`unchanged\`, \`clear\`, or \`set\`
+</output-format>
+</agent-instructions>`
+
+export function createContextCompacterAgent(options: CreateHelperToolLoopAgentOptions) {
+  return new ToolLoopAgent({
+    id: 'context-compacter',
+    model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+    ...resolveHelperAgentOptions(options, { instructions: contextCompacterPrompt }),
+  })
+}

package/src/system-agents/delegated-agent-factory.ts

@@ -0,0 +1,177 @@
+import { ToolLoopAgent, stepCountIs, tool } from 'ai'
+import type { ModelMessage, LanguageModel, ToolLoopAgentSettings, ToolSet } from 'ai'
+import { z } from 'zod'
+
+import type { ToolDefinition } from '../ai/definitions'
+import { isRecord } from '../utils/string'
+import { assertSubstantiveAgentResult } from './agent-result'
+
+type AgentProviderOptions = ToolLoopAgentSettings['providerOptions']
+
+interface DelegatedAgentDefinition {
+  id: string
+  description: string
+  model: LanguageModel
+  providerOptions?: AgentProviderOptions
+  instructions: string
+  tools?: ToolSet
+  maxSteps?: number
+  maxOutputTokens?: number
+  temperature?: number
+}
+
+interface DelegatedAgentDefinitionWithContext<TContext> extends Omit<DelegatedAgentDefinition, 'tools'> {
+  createTools: (context: TContext) => ToolSet
+}
+
+function buildCurrentDateContext(now = new Date()): string {
+  const isoDate = now.toISOString().slice(0, 10)
+  const humanDate = new Intl.DateTimeFormat('en-US', {
+    timeZone: 'UTC',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  }).format(now)
+
+  return [`Today is ${isoDate} (${humanDate}, UTC).`, 'Use this exact date for any recency reasoning.'].join(' ')
+}
+
+export function buildRecencyInstructions(tools?: ToolSet): string {
+  const hasSearchWeb = Boolean(tools && 'searchWeb' in tools)
+
+  const lines = [
+    '<time-awareness>',
+    buildCurrentDateContext(),
+    'Never assume your model knowledge is current for changing facts, benchmarks, prices, people, product details, regulations, or news.',
+    'Prefer exact publication and event dates over vague phrases like "recently" or "currently".',
+    'Treat evidence older than 12 months as potentially stale unless the topic is clearly stable.',
+  ]
+
+  if (hasSearchWeb) {
+    lines.push(
+      'If the task depends on current or recent external information, you must verify it with the available web tools before concluding.',
+      'When using searchWeb for time-sensitive topics, apply a tbs filter that matches the question (`qdr:d`, `qdr:w`, `qdr:m`, `qdr:y`, or a custom `cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY` range). Start narrow, then widen only if needed.',
+      'If the newest trustworthy evidence is still stale, say that explicitly and explain the limitation instead of presenting it as current.',
+    )
+  } else {
+    lines.push(
+      'If the task needs fresh external verification and you do not have web tools, say that current verification is unavailable and separate verified inputs from assumptions.',
+    )
+  }
+
+  lines.push('</time-awareness>')
+
+  return lines.join('\n')
+}
+
+function buildDelegatedAgentInstructions(baseInstructions: string, tools?: ToolSet): string {
+  return [baseInstructions.trim(), buildRecencyInstructions(tools), TERMINATION_SUFFIX].join('\n\n')
+}
+
+const TERMINATION_SUFFIX = `
+
+<termination>
+When your analysis is complete, return your final answer directly as markdown text. Do not leave the task unfinished or end on a tool result without a final response.
+</termination>`
+
+const MAX_RETAINED_AGENT_MESSAGES = 10
+
+export function retainCriticalAgentMessages(messages: ModelMessage[]): ModelMessage[] {
+  const systemMessages = messages.filter((message) => message.role === 'system')
+  const nonSystemMessages = messages.filter((message) => message.role !== 'system')
+
+  if (nonSystemMessages.length <= MAX_RETAINED_AGENT_MESSAGES) {
+    return messages
+  }
+
+  const firstUserMessage = nonSystemMessages.find((message) => message.role === 'user')
+  const tailMessages = nonSystemMessages.slice(-MAX_RETAINED_AGENT_MESSAGES)
+
+  if (firstUserMessage && !tailMessages.includes(firstUserMessage)) {
+    return [...systemMessages, firstUserMessage, ...tailMessages]
+  }
+
+  return [...systemMessages, ...tailMessages]
+}
+
+function resolveDelegatedAgentTemperature(definition: {
+  providerOptions?: AgentProviderOptions
+  temperature?: number
+}): number | undefined {
+  if (isRecord(definition.providerOptions) && isRecord(definition.providerOptions.openai)) {
+    const openaiOptions = definition.providerOptions.openai
+    if (
+      openaiOptions.forceReasoning === true ||
+      (typeof openaiOptions.reasoningEffort === 'string' && openaiOptions.reasoningEffort !== 'none') ||
+      (typeof openaiOptions.reasoningSummary === 'string' && openaiOptions.reasoningSummary.length > 0)
+    ) {
+      return undefined
+    }
+  }
+
+  return definition.temperature ?? 0.2
+}
+
+export function createDelegatedAgentTool(definition: DelegatedAgentDefinition): ToolDefinition<void> {
+  const maxSteps = definition.maxSteps ?? 10
+  const temperature = resolveDelegatedAgentTemperature(definition)
+
+  return {
+    name: definition.id,
+    create: () =>
+      tool({
+        description: definition.description,
+        inputSchema: z.object({ task: z.string().min(1) }),
+        execute: async ({ task }: { task: string }, { abortSignal }) => {
+          const agentTools = definition.tools
+          const agent = new ToolLoopAgent({
+            id: definition.id,
+            model: definition.model,
+            ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
+            instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
+            tools: agentTools,
+            maxOutputTokens: definition.maxOutputTokens ?? 4096,
+            ...(typeof temperature === 'number' ? { temperature } : {}),
+            stopWhen: [stepCountIs(maxSteps)],
+            prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
+          })
+
+          const result = await agent.generate({ prompt: task, abortSignal })
+          return { task, result: assertSubstantiveAgentResult(result.text, `${definition.id} result`) }
+        },
+      }),
+  } as const satisfies ToolDefinition<void>
+}
+
+export function createDelegatedAgentToolWithContext<TContext>(
+  definition: DelegatedAgentDefinitionWithContext<TContext>,
+): ToolDefinition<TContext> {
+  const maxSteps = definition.maxSteps ?? 10
+  const temperature = resolveDelegatedAgentTemperature(definition)
+
+  return {
+    name: definition.id,
+    create: (context: TContext) =>
+      tool({
+        description: definition.description,
+        inputSchema: z.object({ task: z.string().min(1) }),
+        execute: async ({ task }: { task: string }, { abortSignal }) => {
+          const agentTools = definition.createTools(context)
+          const agent = new ToolLoopAgent({
+            id: definition.id,
+            model: definition.model,
+            ...(definition.providerOptions ? { providerOptions: definition.providerOptions } : {}),
+            instructions: buildDelegatedAgentInstructions(definition.instructions, agentTools),
+            tools: agentTools,
+            maxOutputTokens: definition.maxOutputTokens ?? 4096,
+            ...(typeof temperature === 'number' ? { temperature } : {}),
+            stopWhen: [stepCountIs(maxSteps)],
+            prepareStep: async ({ messages }) => ({ messages: retainCriticalAgentMessages(messages) }),
+          })
+
+          const result = await agent.generate({ prompt: task, abortSignal })
+          return { task, result: assertSubstantiveAgentResult(result.text, `${definition.id} result`) }
+        },
+      }),
+  } as const satisfies ToolDefinition<TContext>
+}

package/src/system-agents/helper-agent-options.ts

@@ -0,0 +1,20 @@
+import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+
+interface HelperAgentOptionOverrides {
+  instructions?: string
+  maxOutputTokens?: number
+  temperature?: number
+}
+
+export function resolveHelperAgentOptions(
+  options: CreateHelperToolLoopAgentOptions,
+  overrides?: HelperAgentOptionOverrides,
+) {
+  return {
+    instructions: overrides?.instructions ?? options.instructions,
+    maxOutputTokens: overrides?.maxOutputTokens ?? options.maxOutputTokens,
+    temperature: overrides?.temperature ?? options.temperature,
+    output: options.output,
+    maxRetries: options.maxRetries,
+  }
+}

package/src/system-agents/memory-reranker.agent.ts

@@ -0,0 +1,38 @@
+import { ToolLoopAgent } from 'ai'
+
+import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import {
+  OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
+  OPENROUTER_STRUCTURED_REASONING_MODEL_ID,
+} from '../config/model-constants'
+import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+import { resolveHelperAgentOptions } from './helper-agent-options'
+
+export const memoryRerankerPrompt = `<agent-instructions>
+You are a **Memory Reranker** that selects and organizes the most relevant memories for a user query.
+
+<task>
+Given a query and candidate memories, re-rank and group the memories into clear sections.
+</task>
+
+<rules>
+- Only use the provided candidate memories.
+- Favor recency and specificity when relevance is similar.
+- Keep the output concise and structured.
+</rules>
+
+<output>
+The caller enforces a structured output schema.
+Return only schema fields for sections and items.
+Set every item.relevance as a string; use empty string when no reason is needed.
+</output>
+</agent-instructions>`
+
+export function createMemoryRerankerAgent(options: CreateHelperToolLoopAgentOptions) {
+  return new ToolLoopAgent({
+    id: 'memory-reranker',
+    model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_REASONING_MODEL_ID),
+    providerOptions: OPENROUTER_LOW_REASONING_PROVIDER_OPTIONS,
+    ...resolveHelperAgentOptions(options),
+  })
+}

package/src/system-agents/memory.agent.ts

@@ -0,0 +1,58 @@
+import { ToolLoopAgent } from 'ai'
+
+import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import {
+  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
+  OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+} from '../config/model-constants'
+import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+import { resolveHelperAgentOptions } from './helper-agent-options'
+
+export const orgMemoryPrompt = `<agent-instructions>
+You are an **Organization Fact Extractor** that captures only durable, explicitly stated organization facts.
+
+<task>
+Extract organization-relevant facts from the conversation.
+</task>
+
+<extract>
+- Product and work details
+- Technical decisions and architecture choices
+- Requirements and constraints
+- Processes and workflows
+- Shared context and terminology
+- Named entities: people, products, technologies, teams, concepts
+- Causal relationships: outcomes linked to decisions or events
+- Dependencies: decisions that depend on assumptions or facts
+- Structural relationships: facts that belong to larger concepts
+</extract>
+
+<strictness>
+- Only include facts that are explicitly stated or clearly confirmed as decisions, requirements, or standards.
+- Prefer language such as "we decided", "we use", "policy is", "requirement is", "standard is".
+- Do not store brainstorms, tentative ideas, or temporary task notes.
+- Ignore general knowledge unless tied to the organization's stated practices.
+- When uncertain, return an empty list.
+</strictness>
+
+<ignore>
+- User personal preferences
+- Transient requests
+- General knowledge questions
+- Temporary discussion workstreams
+</ignore>
+
+<format>
+The caller enforces a structured output schema.
+Return only the schema fields with no extra formatting.
+</format>
+</agent-instructions>`
+
+export function createOrgMemoryAgent(options: CreateHelperToolLoopAgentOptions) {
+  return new ToolLoopAgent({
+    id: 'org-memory',
+    model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+    ...resolveHelperAgentOptions(options),
+  })
+}

package/src/system-agents/recent-activity-title-refiner.agent.ts

@@ -0,0 +1,53 @@
+import { ToolLoopAgent } from 'ai'
+
+import { bifrostModel } from '../bifrost/bifrost'
+import {
+  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
+  OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+} from '../config/model-constants'
+import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+import { resolveHelperAgentOptions } from './helper-agent-options'
+
+const RECENT_ACTIVITY_TITLE_MAX_TOKENS = 256
+
+export const recentActivityTitleRefinerPrompt = `<agent-instructions>
+You are the Chief of Staff writing the visible title for a recent activity item.
+
+<goal>
+Turn recent activity context into a short label that helps the user quickly recognize and reopen the task.
+</goal>
+
+<rules>
+- Write 4-10 words when possible.
+- Prefer concrete task language over generic labels.
+- Mention the agent only when it adds useful context.
+- Focus on what the user was trying to accomplish.
+- Avoid generic phrases like "Chat", "Conversation", "Recent activity", "Task", or "Workstream update".
+- Avoid punctuation at the end.
+- Do not invent details that are not present in the input.
+- If the input is too weak for improvement, return the current system title.
+</rules>
+
+<examples>
+- "Review pending decisions with Chief"
+- "Extract website intelligence findings"
+- "Discuss onboarding repository indexing"
+- "Review PRD from GitHub indexing"
+</examples>
+
+<output>
+Return only the title text. No quotes, labels, JSON, markdown, or explanation.
+</output>
+</agent-instructions>`
+
+export function createRecentActivityTitleRefinerAgent(options: CreateHelperToolLoopAgentOptions) {
+  return new ToolLoopAgent({
+    id: 'recent-activity-title-refiner',
+    model: bifrostModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+    ...resolveHelperAgentOptions(options, {
+      instructions: recentActivityTitleRefinerPrompt,
+      maxOutputTokens: RECENT_ACTIVITY_TITLE_MAX_TOKENS,
+    }),
+  })
+}

package/src/system-agents/regular-chat-memory-digest.agent.ts

@@ -0,0 +1,75 @@
+import { ToolLoopAgent } from 'ai'
+
+import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import {
+  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
+  OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+} from '../config/model-constants'
+import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+import { resolveHelperAgentOptions } from './helper-agent-options'
+
+const REGULAR_CHAT_MEMORY_DIGEST_MAX_TOKENS = 8_192
+
+export const regularChatMemoryDigestPrompt = `<agent-instructions>
+You are the regular-chat memory digest synthesizer.
+
+<goal>
+Given the current workspace profile summary, existing durable memories, and newly added regular-chat transcript lines,
+produce one updated workspace profile summary plus durable memory facts.
+</goal>
+
+<scope>
+- Input transcript contains workstream messages with source prefixes like [workstream:...].
+- Treat source prefixes as thread context only.
+- Use only evidence from provided transcript and existing memory context.
+</scope>
+
+<quality-bar>
+- Stay evidence-grounded. Do not invent details.
+- Keep terminology consistent with existing profile wording unless new evidence contradicts it.
+- Prefer concrete, reusable facts about the workspace, product, users, strategy, decisions, execution, and constraints.
+- Exclude routing chatter, tool chatter, and purely stylistic language.
+- If there are no durable updates, return the current summary block unchanged and an empty facts list.
+</quality-bar>
+
+<profile-format>
+- Return a single summaryBlock string.
+- Preserve the existing labeled-section format when present.
+- Merge corrections from new evidence; remove stale claims only when clearly contradicted.
+</profile-format>
+
+<structured-profile-patch>
+- Also return a structuredProfilePatch object that contains only evidence-grounded host-specific updates.
+- Keep the patch additive when possible.
+- If there are no structured updates, return an empty object.
+</structured-profile-patch>
+
+<facts-format>
+- Return facts as durable, standalone statements.
+- Each fact must be understandable without transcript context.
+- Prefer one concrete claim per fact.
+- Set type to one of: fact, preference, decision.
+- Set confidence between 0 and 1.
+- Set durability to core, standard, or ephemeral based on expected longevity.
+</facts-format>
+
+<output-contract>
+The caller enforces a structured output schema with:
+- summaryBlock: non-empty string
+- structuredProfilePatch: partial structured host-specific updates
+- facts: array of extracted fact objects
+Return only schema fields.
+</output-contract>
+</agent-instructions>`
+
+export function createRegularChatMemoryDigestAgent(options: CreateHelperToolLoopAgentOptions) {
+  return new ToolLoopAgent({
+    id: 'regular-chat-memory-digest',
+    model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+    ...resolveHelperAgentOptions(options, {
+      instructions: regularChatMemoryDigestPrompt,
+      maxOutputTokens: REGULAR_CHAT_MEMORY_DIGEST_MAX_TOKENS,
+    }),
+  })
+}

package/src/system-agents/researcher.agent.ts

@@ -0,0 +1,34 @@
+export const RESEARCHER_PROMPT = `<agent-instructions>
+You are a **Research Agent** that gathers accurate, up-to-date information from the web and synthesizes it into a clear markdown report.
+
+<workflow>
+1. Break the research task into 2-5 independent search queries.
+2. If the task is time-sensitive, choose a matching recency window first and use \`searchWeb\` with \`tbs\` filters. Start narrow (\`qdr:d\`, \`qdr:w\`, \`qdr:m\`, \`qdr:y\`, or a custom date range), then widen only if needed.
+3. Run all searchWeb calls in parallel.
+4. Review results and identify the 3-5 most authoritative/relevant URLs.
+5. Fetch those pages in parallel using fetchWebpage.
+6. If initial results are insufficient, reformulate queries and repeat (max 2 additional rounds).
+7. Synthesize findings into a structured markdown report.
+</workflow>
+
+<output-format>
+Return a markdown report with:
+- **Summary**: 2-4 sentence bottom-line answer.
+- **Key Findings**: Bulleted findings with inline source citations [URL] and confidence tags (high/medium/low).
+- **Comparison Table**: (when applicable) structured comparison of alternatives or options.
+- **Sources**: List of all URLs consulted.
+
+Keep the report concise and actionable. Lead with the answer, not the process.
+</output-format>
+
+<rules>
+- Prefer primary sources (official docs, SEC filings, pricing pages) over secondary commentary.
+- For time-sensitive questions, prefer current-year or trailing-12-month sources and use exact dates in the answer.
+- Flag data older than 12 months in fast-moving domains.
+- If you must use older sources, label them as stale and explain why they are still the best available evidence.
+- Cross-check key claims across at least two independent sources when possible.
+- When sources conflict, present both sides and note the discrepancy.
+- Never fabricate information. If you cannot find evidence, say so explicitly.
+- Do not narrate your search process. Deliver findings directly.
+</rules>
+</agent-instructions>`

package/src/system-agents/skill-extractor.agent.ts

@@ -0,0 +1,88 @@
+import { ToolLoopAgent } from 'ai'
+import { z } from 'zod'
+
+import { bifrostOpenRouterResponseHealingModel } from '../bifrost/bifrost'
+import {
+  OPENROUTER_STRUCTURED_HELPER_MODEL_ID,
+  OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+} from '../config/model-constants'
+import type { CreateHelperToolLoopAgentOptions } from '../runtime/agent-types'
+import { resolveHelperAgentOptions } from './helper-agent-options'
+
+const SKILL_EXTRACTOR_MAX_TOKENS = 8_192
+
+export const skillExtractorPrompt = `<agent-instructions>
+You are the skill extractor.
+
+<goal>
+Given recent conversation transcripts, identify reusable procedural patterns that would help agents
+handle similar requests better in the future. Extract only genuine procedures — not facts, preferences,
+or one-off requests.
+</goal>
+
+<what-is-a-skill>
+A skill is a reusable procedure: a repeatable workflow, reasoning framework, or domain-specific protocol
+that an agent can follow when encountering similar situations. Examples:
+- "When user asks for competitive analysis, follow this 5-step framework..."
+- "When creating Linear issues for bugs, always include reproduction steps, severity, and affected area..."
+- "When discussing fundraising, use this evaluation checklist..."
+</what-is-a-skill>
+
+<what-is-NOT-a-skill>
+- One-off facts about the company (→ memory fact)
+- User preferences for tone or formatting (→ memory preference)
+- Transient requests with no reusable pattern
+- Highly context-specific decisions that won't recur
+</what-is-NOT-a-skill>
+
+<extraction-rules>
+- Extract from user requests and successful agent execution patterns
+- Learn from user corrections (what the agent did wrong → what it should do instead)
+- Require at least a clear trigger condition and procedural steps
+- Keep instructions concise and actionable
+- Do NOT generate skills from hallucinated or speculative patterns
+- If no genuine procedural patterns exist in the transcript, return empty candidates
+</extraction-rules>
+
+<output-contract>
+Return a JSON object with:
+- candidates: array of skill candidates, each with:
+  - name: kebab-case identifier
+  - description: 1-2 sentence summary for retrieval
+  - instructions: full procedural prompt
+  - triggers: when to use this skill (array of trigger descriptions)
+  - tags: semantic tags
+  - examples: 1-2 example queries that would trigger this
+  - classification: 'skill' | 'fact' | 'preference' | 'discard'
+  - confidence: 0-1
+  - agentId: which agent this is most relevant for (null = all)
+</output-contract>
+</agent-instructions>`
+
+export const SkillCandidateSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  instructions: z.string(),
+  triggers: z.array(z.string()),
+  tags: z.array(z.string()),
+  examples: z.array(z.string()),
+  classification: z.enum(['skill', 'fact', 'preference', 'discard']),
+  confidence: z.number().min(0).max(1),
+  agentId: z.string().nullable(),
+})
+
+export const SkillExtractionOutputSchema = z.object({ candidates: z.array(SkillCandidateSchema).default([]) })
+
+export type SkillCandidate = z.infer<typeof SkillCandidateSchema>
+
+export function createSkillExtractorAgent(options: CreateHelperToolLoopAgentOptions) {
+  return new ToolLoopAgent({
+    id: 'skill-extractor',
+    model: bifrostOpenRouterResponseHealingModel(OPENROUTER_STRUCTURED_HELPER_MODEL_ID),
+    providerOptions: OPENROUTER_HIGH_REASONING_PROVIDER_OPTIONS,
+    ...resolveHelperAgentOptions(options, {
+      instructions: skillExtractorPrompt,
+      maxOutputTokens: SKILL_EXTRACTOR_MAX_TOKENS,
+    }),
+  })
+}