@lota-sdk/core 0.1.5

package/infrastructure/schema/00_workstream.surql

@@ -0,0 +1,55 @@
+# Workstream table.
+DEFINE TABLE IF NOT EXISTS workstream SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS organizationId ON TABLE workstream TYPE record<organization>;
+DEFINE FIELD IF NOT EXISTS userId ON TABLE workstream TYPE record<user>;
+DEFINE FIELD IF NOT EXISTS agentId ON TABLE workstream TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS mode ON TABLE workstream TYPE string DEFAULT 'group';
+DEFINE FIELD IF NOT EXISTS core ON TABLE workstream TYPE bool DEFAULT false;
+DEFINE FIELD IF NOT EXISTS coreType ON TABLE workstream TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS title ON TABLE workstream TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS status ON TABLE workstream TYPE string DEFAULT 'regular';
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE workstream TYPE datetime DEFAULT time::now() READONLY;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE workstream TYPE datetime VALUE time::now();
+DEFINE FIELD IF NOT EXISTS memoryBlock ON TABLE workstream TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS memoryBlockSummary ON TABLE workstream TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS activeRunId ON TABLE workstream TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS chatSummary ON TABLE workstream TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS lastCompactedMessageId ON TABLE workstream TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS isCompacting ON TABLE workstream TYPE bool DEFAULT false;
+DEFINE FIELD IF NOT EXISTS state ON TABLE workstream TYPE option<object> FLEXIBLE;
+
+DEFINE INDEX IF NOT EXISTS workstreamOrgIdx ON TABLE workstream COLUMNS organizationId;
+
+# Workstream Message table (AI SDK UIMessage persistence).
+# parts uses OVERWRITE on the wildcard to override the implicit non-FLEXIBLE
+# definition that array<object> creates — this is the only way to allow
+# arbitrary nested object shapes inside the array on SCHEMAFULL tables.
+DEFINE TABLE IF NOT EXISTS workstreamMessage SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS workstreamId ON TABLE workstreamMessage TYPE record<workstream> REFERENCE ON DELETE CASCADE;
+DEFINE FIELD IF NOT EXISTS messageId ON TABLE workstreamMessage TYPE string;
+DEFINE FIELD IF NOT EXISTS role ON TABLE workstreamMessage TYPE string;
+DEFINE FIELD IF NOT EXISTS parts ON TABLE workstreamMessage TYPE array<object> FLEXIBLE;
+DEFINE FIELD OVERWRITE parts.* ON TABLE workstreamMessage TYPE object FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS metadata ON TABLE workstreamMessage TYPE option<object> FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE workstreamMessage TYPE datetime DEFAULT time::now() READONLY;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE workstreamMessage TYPE datetime VALUE time::now();
+
+DEFINE INDEX IF NOT EXISTS workstreamMessageWorkstreamIdx ON TABLE workstreamMessage COLUMNS workstreamId;
+DEFINE INDEX IF NOT EXISTS workstreamMessageWorkstreamCreatedIdx ON TABLE workstreamMessage COLUMNS workstreamId, createdAt;
+DEFINE INDEX IF NOT EXISTS workstreamMessageWorkstreamMessageUniqueIdx ON TABLE workstreamMessage COLUMNS workstreamId, messageId UNIQUE;
+
+# Workstream attachments.
+DEFINE TABLE IF NOT EXISTS workstreamAttachment SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS workstreamId ON TABLE workstreamAttachment TYPE record<workstream> REFERENCE ON DELETE CASCADE;
+DEFINE FIELD IF NOT EXISTS messageId ON TABLE workstreamAttachment TYPE record<workstreamMessage> REFERENCE ON DELETE CASCADE;
+DEFINE FIELD IF NOT EXISTS attachmentType ON TABLE workstreamAttachment TYPE string;
+DEFINE FIELD IF NOT EXISTS name ON TABLE workstreamAttachment TYPE string;
+DEFINE FIELD IF NOT EXISTS contentType ON TABLE workstreamAttachment TYPE string;
+DEFINE FIELD IF NOT EXISTS storageKey ON TABLE workstreamAttachment TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS sizeBytes ON TABLE workstreamAttachment TYPE option<int>;
+DEFINE FIELD IF NOT EXISTS url ON TABLE workstreamAttachment TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE workstreamAttachment TYPE datetime DEFAULT time::now() READONLY;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE workstreamAttachment TYPE datetime VALUE time::now();
+
+DEFINE INDEX IF NOT EXISTS workstreamAttachmentWorkstreamIdx ON TABLE workstreamAttachment COLUMNS workstreamId;
+DEFINE INDEX IF NOT EXISTS workstreamAttachmentMessageIdx ON TABLE workstreamAttachment COLUMNS messageId;

package/infrastructure/schema/01_memory.surql

@@ -0,0 +1,47 @@
+# Memory tables for chat memory system.
+DEFINE TABLE IF NOT EXISTS memory SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS content ON TABLE memory TYPE string;
+DEFINE FIELD IF NOT EXISTS embedding ON TABLE memory TYPE array<float>;
+DEFINE FIELD IF NOT EXISTS hash ON TABLE memory TYPE string;
+DEFINE FIELD IF NOT EXISTS scopeId ON TABLE memory TYPE string;
+# memoryType: fact, preference, interaction, summary, user_request, entity, interest
+DEFINE FIELD IF NOT EXISTS memoryType ON TABLE memory TYPE string;
+-- Memory metadata evolves (orgId, sessionId, etc.). Keep it flexible.
+DEFINE FIELD IF NOT EXISTS metadata ON TABLE memory TYPE object FLEXIBLE DEFAULT {};
+# durability: core (business decisions, 0% decay), standard (general facts, 5% decay), ephemeral (preferences, 15% decay)
+DEFINE FIELD IF NOT EXISTS durability ON TABLE memory TYPE string DEFAULT 'standard';
+DEFINE FIELD IF NOT EXISTS importance ON TABLE memory TYPE float DEFAULT 1.0;
+DEFINE FIELD IF NOT EXISTS accessCount ON TABLE memory TYPE int DEFAULT 0;
+DEFINE FIELD IF NOT EXISTS lastAccessedAt ON TABLE memory TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE memory TYPE datetime DEFAULT time::now() READONLY;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE memory TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS validFrom ON TABLE memory TYPE datetime DEFAULT time::now();
+DEFINE FIELD IF NOT EXISTS validUntil ON TABLE memory TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS archivedAt ON TABLE memory TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS needsReview ON TABLE memory TYPE bool DEFAULT false;
+
+DEFINE TABLE IF NOT EXISTS memoryRelation SCHEMAFULL TYPE RELATION IN memory OUT memory;
+# relationType: contradicts, supports, supersedes, caused_by, depends_on, part_of, implements
+DEFINE FIELD IF NOT EXISTS relationType ON TABLE memoryRelation TYPE string;
+DEFINE FIELD IF NOT EXISTS confidence ON TABLE memoryRelation TYPE float DEFAULT 1.0;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE memoryRelation TYPE datetime DEFAULT time::now() READONLY;
+
+DEFINE TABLE IF NOT EXISTS memoryHistory SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS memoryId ON TABLE memoryHistory TYPE record<memory>;
+DEFINE FIELD IF NOT EXISTS prevValue ON TABLE memoryHistory TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS newValue ON TABLE memoryHistory TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS event ON TABLE memoryHistory TYPE string;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE memoryHistory TYPE datetime DEFAULT time::now() READONLY;
+
+DEFINE ANALYZER IF NOT EXISTS memoryAnalyzer TOKENIZERS blank, class, punct FILTERS lowercase, snowball(english);
+DEFINE INDEX IF NOT EXISTS memoryVectorIdx ON TABLE memory FIELDS embedding HNSW DIMENSION 1536 DIST COSINE TYPE F32;
+DEFINE INDEX IF NOT EXISTS memoryContentFts ON TABLE memory FIELDS content FULLTEXT ANALYZER memoryAnalyzer BM25 HIGHLIGHTS;
+DEFINE INDEX IF NOT EXISTS memoryScopeIdIdx ON TABLE memory COLUMNS scopeId;
+DEFINE INDEX IF NOT EXISTS memoryHashIdx ON TABLE memory COLUMNS hash UNIQUE;
+DEFINE INDEX IF NOT EXISTS memoryArchivedIdx ON TABLE memory COLUMNS archivedAt;
+DEFINE INDEX IF NOT EXISTS memoryScopeTypeArchivedIdx ON TABLE memory COLUMNS scopeId, memoryType, archivedAt;
+DEFINE INDEX IF NOT EXISTS memoryScopeTemporalIdx ON TABLE memory COLUMNS scopeId, archivedAt, validFrom, validUntil;
+DEFINE INDEX IF NOT EXISTS memoryNeedsReviewIdx ON TABLE memory COLUMNS scopeId, needsReview, archivedAt, updatedAt;
+DEFINE INDEX IF NOT EXISTS memoryTopLookupIdx ON TABLE memory COLUMNS scopeId, memoryType, durability, archivedAt, importance, accessCount, lastAccessedAt, createdAt;
+DEFINE INDEX IF NOT EXISTS memoryRelationOutTypeIdx ON TABLE memoryRelation COLUMNS out, relationType;
+DEFINE INDEX IF NOT EXISTS memoryRelationInTypeIdx ON TABLE memoryRelation COLUMNS in, relationType;

package/infrastructure/schema/02_execution_plan.surql

@@ -0,0 +1,62 @@
+# Execution plan runtime.
+DEFINE TABLE IF NOT EXISTS plan SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS organizationId ON TABLE plan TYPE record<organization>;
+DEFINE FIELD IF NOT EXISTS workstreamId ON TABLE plan TYPE record<workstream> REFERENCE ON DELETE CASCADE;
+DEFINE FIELD IF NOT EXISTS title ON TABLE plan TYPE string;
+DEFINE FIELD IF NOT EXISTS objective ON TABLE plan TYPE string;
+DEFINE FIELD IF NOT EXISTS status ON TABLE plan TYPE string;
+DEFINE FIELD IF NOT EXISTS leadAgentId ON TABLE plan TYPE string;
+DEFINE FIELD IF NOT EXISTS currentTaskId ON TABLE plan TYPE option<record<planTask>>;
+DEFINE FIELD IF NOT EXISTS restartFromTaskId ON TABLE plan TYPE option<record<planTask>>;
+DEFINE FIELD IF NOT EXISTS replacedPlanId ON TABLE plan TYPE option<record<plan>>;
+DEFINE FIELD IF NOT EXISTS failureCount ON TABLE plan TYPE int DEFAULT 0;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE plan TYPE datetime DEFAULT time::now() READONLY;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE plan TYPE datetime VALUE time::now();
+DEFINE FIELD IF NOT EXISTS startedAt ON TABLE plan TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS completedAt ON TABLE plan TYPE option<datetime>;
+
+DEFINE INDEX IF NOT EXISTS planWorkstreamIdx ON TABLE plan COLUMNS workstreamId;
+DEFINE INDEX IF NOT EXISTS planWorkstreamStatusIdx ON TABLE plan COLUMNS workstreamId, status;
+
+DEFINE TABLE IF NOT EXISTS planTask SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS planId ON TABLE planTask TYPE record<plan> REFERENCE ON DELETE CASCADE;
+DEFINE FIELD IF NOT EXISTS organizationId ON TABLE planTask TYPE record<organization>;
+DEFINE FIELD IF NOT EXISTS workstreamId ON TABLE planTask TYPE record<workstream>;
+DEFINE FIELD IF NOT EXISTS position ON TABLE planTask TYPE int;
+DEFINE FIELD IF NOT EXISTS title ON TABLE planTask TYPE string;
+DEFINE FIELD IF NOT EXISTS rationale ON TABLE planTask TYPE string;
+DEFINE FIELD IF NOT EXISTS kind ON TABLE planTask TYPE string;
+DEFINE FIELD IF NOT EXISTS ownerType ON TABLE planTask TYPE string;
+DEFINE FIELD IF NOT EXISTS ownerRef ON TABLE planTask TYPE string;
+DEFINE FIELD IF NOT EXISTS status ON TABLE planTask TYPE string;
+DEFINE FIELD IF NOT EXISTS resultStatus ON TABLE planTask TYPE string DEFAULT 'not-started';
+DEFINE FIELD IF NOT EXISTS input ON TABLE planTask TYPE option<object | string> FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS outputSummary ON TABLE planTask TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS blockedReason ON TABLE planTask TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS externalRef ON TABLE planTask TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS retryCount ON TABLE planTask TYPE int DEFAULT 0;
+DEFINE FIELD IF NOT EXISTS idempotencyKey ON TABLE planTask TYPE string;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE planTask TYPE datetime DEFAULT time::now() READONLY;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE planTask TYPE datetime VALUE time::now();
+DEFINE FIELD IF NOT EXISTS startedAt ON TABLE planTask TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS completedAt ON TABLE planTask TYPE option<datetime>;
+
+DEFINE INDEX IF NOT EXISTS planTaskPlanPositionIdx ON TABLE planTask COLUMNS planId, position;
+DEFINE INDEX IF NOT EXISTS planTaskPlanStatusIdx ON TABLE planTask COLUMNS planId, status;
+DEFINE INDEX IF NOT EXISTS planTaskIdempotencyIdx ON TABLE planTask COLUMNS idempotencyKey UNIQUE;
+
+DEFINE TABLE IF NOT EXISTS planEvent SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS planId ON TABLE planEvent TYPE record<plan> REFERENCE ON DELETE CASCADE;
+DEFINE FIELD IF NOT EXISTS taskId ON TABLE planEvent TYPE option<record<planTask>>;
+DEFINE FIELD IF NOT EXISTS eventType ON TABLE planEvent TYPE string;
+DEFINE FIELD IF NOT EXISTS fromStatus ON TABLE planEvent TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS toStatus ON TABLE planEvent TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS message ON TABLE planEvent TYPE string;
+DEFINE FIELD IF NOT EXISTS detail ON TABLE planEvent TYPE option<object> FLEXIBLE;
+DEFINE FIELD IF NOT EXISTS emittedBy ON TABLE planEvent TYPE string;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE planEvent TYPE datetime DEFAULT time::now() READONLY;
+
+DEFINE INDEX IF NOT EXISTS planEventPlanIdx ON TABLE planEvent COLUMNS planId;
+DEFINE INDEX IF NOT EXISTS planEventTaskIdx ON TABLE planEvent COLUMNS taskId;
+DEFINE INDEX IF NOT EXISTS planEventTypeIdx ON TABLE planEvent COLUMNS planId, eventType;
+DEFINE INDEX IF NOT EXISTS planEventTimeIdx ON TABLE planEvent COLUMNS planId, createdAt;

package/infrastructure/schema/03_learned_skill.surql

@@ -0,0 +1,32 @@
+# Learned skills table — stores reusable procedural knowledge extracted from conversations.
+DEFINE TABLE IF NOT EXISTS learnedSkill SCHEMAFULL;
+
+DEFINE FIELD IF NOT EXISTS name ON TABLE learnedSkill TYPE string;
+DEFINE FIELD IF NOT EXISTS description ON TABLE learnedSkill TYPE string;
+DEFINE FIELD IF NOT EXISTS instructions ON TABLE learnedSkill TYPE string;
+DEFINE FIELD IF NOT EXISTS triggers ON TABLE learnedSkill TYPE array<string> DEFAULT [];
+DEFINE FIELD IF NOT EXISTS tags ON TABLE learnedSkill TYPE array<string> DEFAULT [];
+DEFINE FIELD IF NOT EXISTS examples ON TABLE learnedSkill TYPE array<string> DEFAULT [];
+DEFINE FIELD IF NOT EXISTS version ON TABLE learnedSkill TYPE int DEFAULT 1;
+DEFINE FIELD IF NOT EXISTS sourceType ON TABLE learnedSkill TYPE string;
+DEFINE FIELD IF NOT EXISTS organizationId ON TABLE learnedSkill TYPE record<organization>;
+DEFINE FIELD IF NOT EXISTS agentId ON TABLE learnedSkill TYPE option<string>;
+DEFINE FIELD IF NOT EXISTS status ON TABLE learnedSkill TYPE string DEFAULT 'learned';
+DEFINE FIELD IF NOT EXISTS confidence ON TABLE learnedSkill TYPE float DEFAULT 0.5;
+DEFINE FIELD IF NOT EXISTS usageCount ON TABLE learnedSkill TYPE int DEFAULT 0;
+DEFINE FIELD IF NOT EXISTS successCount ON TABLE learnedSkill TYPE int DEFAULT 0;
+DEFINE FIELD IF NOT EXISTS supersedes ON TABLE learnedSkill TYPE option<record<learnedSkill>>;
+DEFINE FIELD IF NOT EXISTS embedding ON TABLE learnedSkill TYPE array<float>;
+DEFINE FIELD IF NOT EXISTS hash ON TABLE learnedSkill TYPE string;
+DEFINE FIELD IF NOT EXISTS createdAt ON TABLE learnedSkill TYPE datetime DEFAULT time::now() READONLY;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE learnedSkill TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS lastUsedAt ON TABLE learnedSkill TYPE option<datetime>;
+DEFINE FIELD IF NOT EXISTS archivedAt ON TABLE learnedSkill TYPE option<datetime>;
+
+# Indexes
+DEFINE ANALYZER IF NOT EXISTS learnedSkillAnalyzer TOKENIZERS blank, class, punct FILTERS lowercase, snowball(english);
+DEFINE INDEX IF NOT EXISTS learnedSkillVectorIdx ON TABLE learnedSkill FIELDS embedding HNSW DIMENSION 1536 DIST COSINE TYPE F32;
+DEFINE INDEX IF NOT EXISTS learnedSkillContentFts ON TABLE learnedSkill FIELDS description FULLTEXT ANALYZER learnedSkillAnalyzer BM25 HIGHLIGHTS;
+DEFINE INDEX IF NOT EXISTS learnedSkillOrgIdx ON TABLE learnedSkill COLUMNS organizationId;
+DEFINE INDEX IF NOT EXISTS learnedSkillStatusIdx ON TABLE learnedSkill COLUMNS organizationId, status, archivedAt;
+DEFINE INDEX IF NOT EXISTS learnedSkillHashIdx ON TABLE learnedSkill COLUMNS hash UNIQUE;

package/infrastructure/schema/04_runtime_bootstrap.surql

@@ -0,0 +1,8 @@
+# Runtime bootstrap readiness state.
+DEFINE TABLE IF NOT EXISTS runtimeBootstrap SCHEMAFULL;
+DEFINE FIELD IF NOT EXISTS key ON TABLE runtimeBootstrap TYPE string;
+DEFINE FIELD IF NOT EXISTS schemaFingerprint ON TABLE runtimeBootstrap TYPE string;
+DEFINE FIELD IF NOT EXISTS readyAt ON TABLE runtimeBootstrap TYPE datetime;
+DEFINE FIELD IF NOT EXISTS updatedAt ON TABLE runtimeBootstrap TYPE datetime VALUE time::now();
+
+DEFINE INDEX IF NOT EXISTS runtimeBootstrapKeyUniqueIdx ON TABLE runtimeBootstrap COLUMNS key UNIQUE;

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@lota-sdk/core",
+  "version": "0.1.5",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "infrastructure/schema"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./ai/*": {
+      "bun": "./src/ai/*.ts",
+      "import": "./src/ai/*.ts",
+      "types": "./src/ai/*.ts"
+    },
+    "./bifrost": {
+      "bun": "./src/bifrost/bifrost.ts",
+      "import": "./src/bifrost/bifrost.ts",
+      "types": "./src/bifrost/bifrost.ts"
+    },
+    "./bifrost/*": {
+      "bun": "./src/bifrost/*.ts",
+      "import": "./src/bifrost/*.ts",
+      "types": "./src/bifrost/*.ts"
+    },
+    "./runtime/*": {
+      "bun": "./src/runtime/*.ts",
+      "import": "./src/runtime/*.ts",
+      "types": "./src/runtime/*.ts"
+    },
+    "./tools/*": {
+      "bun": "./src/tools/*.ts",
+      "import": "./src/tools/*.ts",
+      "types": "./src/tools/*.ts"
+    },
+    "./storage/*": {
+      "bun": "./src/storage/*.ts",
+      "import": "./src/storage/*.ts",
+      "types": "./src/storage/*.ts"
+    },
+    "./document/*": {
+      "bun": "./src/document/*.ts",
+      "import": "./src/document/*.ts",
+      "types": "./src/document/*.ts"
+    },
+    "./system-agents/*": {
+      "bun": "./src/system-agents/*.ts",
+      "import": "./src/system-agents/*.ts",
+      "types": "./src/system-agents/*.ts"
+    },
+    "./db/*": {
+      "bun": "./src/db/*.ts",
+      "import": "./src/db/*.ts",
+      "types": "./src/db/*.ts"
+    },
+    "./redis": {
+      "bun": "./src/redis/index.ts",
+      "import": "./src/redis/index.ts",
+      "types": "./src/redis/index.ts"
+    },
+    "./redis/*": {
+      "bun": "./src/redis/*.ts",
+      "import": "./src/redis/*.ts",
+      "types": "./src/redis/*.ts"
+    },
+    "./services/*": {
+      "bun": "./src/services/*.ts",
+      "import": "./src/services/*.ts",
+      "types": "./src/services/*.ts"
+    },
+    "./config/*": {
+      "bun": "./src/config/*.ts",
+      "import": "./src/config/*.ts",
+      "types": "./src/config/*.ts"
+    },
+    "./utils/*": {
+      "bun": "./src/utils/*.ts",
+      "import": "./src/utils/*.ts",
+      "types": "./src/utils/*.ts"
+    },
+    "./queues/*": {
+      "bun": "./src/queues/*.ts",
+      "import": "./src/queues/*.ts",
+      "types": "./src/queues/*.ts"
+    },
+    "./workers/*": {
+      "bun": "./src/workers/*.ts",
+      "import": "./src/workers/*.ts",
+      "types": "./src/workers/*.ts"
+    },
+    "./embeddings": {
+      "bun": "./src/embeddings/provider.ts",
+      "import": "./src/embeddings/provider.ts",
+      "types": "./src/embeddings/provider.ts"
+    }
+  },
+  "scripts": {
+    "lint": "node ../node_modules/oxlint/bin/oxlint --fix -c ../oxlint.config.ts src",
+    "format": "bunx oxfmt src",
+    "typecheck": "bunx tsgo --noEmit",
+    "test:unit": "bun test ../tests/unit/core"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.41",
+    "@logtape/logtape": "^2.0.4",
+    "@lota-sdk/shared": "0.1.0",
+    "@mendable/firecrawl-js": "^4.16.0",
+    "@surrealdb/node": "^3.0.3",
+    "ai": "^6.0.116",
+    "bullmq": "^5.71.0",
+    "hono": "^4.12.8",
+    "ioredis": "5.9.3",
+    "mammoth": "^1.12.0",
+    "pdf-parse": "^2.4.5",
+    "surrealdb": "^2.0.2",
+    "zod": "^4.3.6"
+  }
+}

package/src/ai/definitions.ts

@@ -0,0 +1,308 @@
+import type { ToolSet } from 'ai'
+
+export interface SkillDefinition<TToolName extends string = string> {
+  name: string
+  description: string
+  instructions: string
+  tools: readonly TToolName[]
+}
+
+export interface RuleDefinition {
+  name: string
+  instructions: string
+}
+
+export interface PromptDefinition {
+  name: string
+  instructions: string
+}
+
+export interface ToolDefinition<TContext> {
+  name: string
+  create: (context: TContext) => ToolSet[string]
+}
+
+export function defineSkill<const TToolName extends string>(definition: SkillDefinition<TToolName>) {
+  return definition
+}
+
+export function defineRule(definition: RuleDefinition) {
+  return definition
+}
+
+export function definePrompt(definition: PromptDefinition) {
+  return definition
+}
+
+function cleanInstructions(value: string): string {
+  return value.trim()
+}
+
+export function renderRuleInstructions(rules: readonly RuleDefinition[]): string {
+  const sections = rules.map((rule) => cleanInstructions(rule.instructions)).filter((value) => value.length > 0)
+  if (sections.length === 0) return ''
+  return ['<rules>', ...sections, '</rules>'].join('\n\n')
+}
+
+export function renderSkillInstructions(skills: readonly SkillDefinition[]): string {
+  const sections = skills.map((skill) => cleanInstructions(skill.instructions)).filter((value) => value.length > 0)
+  if (sections.length === 0) return ''
+  return ['<skills>', ...sections, '</skills>'].join('\n\n')
+}
+
+/** @lintignore */
+export interface LearnedSkillEntry {
+  name: string
+  instructions: string
+}
+
+export function renderLearnedSkillInstructions(skills: readonly LearnedSkillEntry[]): string {
+  const sections = skills
+    .map((skill) => {
+      const instructions = cleanInstructions(skill.instructions)
+      if (!instructions) return ''
+      return `### ${skill.name}\n\n${instructions}`
+    })
+    .filter((value) => value.length > 0)
+  if (sections.length === 0) return ''
+  return [
+    '<learned-skills>',
+    'The following procedures were learned from previous interactions. Apply them when relevant.',
+    '',
+    ...sections,
+    '</learned-skills>',
+  ].join('\n\n')
+}
+
+const askingUserQuestionsSkillTools = ['userQuestions'] as const
+
+export const askingUserQuestionsSkill = defineSkill({
+  name: 'asking-user-questions',
+  description: 'Ask structured clarification questions only when required to proceed safely or accurately.',
+  tools: askingUserQuestionsSkillTools,
+  instructions: `# asking-user-questions
+
+## Description
+
+Use this skill when an answer or action requires missing user input that cannot be inferred reliably.
+
+## Details
+
+<when-to-use>
+- Requirements are ambiguous and different interpretations would change the outcome.
+- A required identifier is missing (for example project/team/owner/issue reference).
+- The user must choose between materially different options.
+- You need explicit consent before a mutation or irreversible action.
+- You need specific business context only the user can provide.
+- The request is ambiguous and proceeding would produce low-quality output.
+- You need approval or confirmation before taking a significant action.
+</when-to-use>
+
+<how-to-use>
+Use the \`userQuestions\` tool to present structured questions. This renders an interactive form in the chat UI and
+terminates the agent chain until the user responds. The user already sees this form, so do **not** restate the same
+questions in plain text. Do **not** call any additional tools in the same response.
+
+### Question types
+
+- \`single-select\` — user picks one option from a list (with optional custom answer field)
+- \`multi-select\` — user picks multiple options from a list (with optional custom answer field)
+- \`input\` — user types a free-text answer
+
+### Schema
+
+\`\`\`json
+{
+  "questions": [
+    { "question": "What is your target market?", "type": "single-select", "options": ["B2B", "B2C", "Both"] },
+    {
+      "question": "Which features do you need?",
+      "type": "multi-select",
+      "options": ["Authentication", "REST API", "Admin Panel", "Analytics"]
+    },
+    { "question": "What is your budget range?", "type": "input" }
+  ]
+}
+\`\`\`
+
+- \`options\` is a plain string array (no IDs needed).
+- \`allowCustomAnswer\` (optional, defaults to \`true\` for select types) adds a free-text field alongside options.
+- Do **not** generate additional text or tool calls after calling \`userQuestions\` (including repeating the questions as
+  plain text). Your turn is complete.
+</how-to-use>
+
+<do-not-use>
+- Do not ask when reasonable defaults are already explicit in the user request.
+- Do not ask for information that can be retrieved using available read tools.
+- Do not ask broad discovery questions when one targeted question will unblock progress.
+</do-not-use>`,
+})
+
+const researchSkillTools = ['researchTopic', 'fetchWebpage', 'inspectWebsite'] as const
+
+export const researchSkill = defineSkill({
+  name: 'research',
+  description:
+    'Delegate research to a dedicated agent for gathering accurate, up-to-date information with source attribution and confidence assessment.',
+  tools: researchSkillTools,
+  instructions: `# research
+
+## Description
+
+Use for any task requiring external information gathering: market research, competitive analysis, technical evaluation,
+fact verification, or source-backed answers. Delegates web research to a dedicated research agent.
+
+## Details
+
+<when-to-use>
+- The user asks a question that requires current, external information beyond the agent's training data.
+- Market sizing, competitor analysis, or industry trend research.
+- Technical evaluation of tools, frameworks, vendors, or platforms.
+- Fact-checking claims, statistics, or benchmarks before using them in deliverables.
+- Gathering evidence to support or challenge a hypothesis from another skill.
+
+Do NOT use when:
+
+- The question can be answered from conversation context or organizational memory alone.
+- The user is asking for coaching, strategy, or opinion (use a domain skill instead).
+- The task is purely internal (roadmap prioritization, team dynamics, financial modeling from known data).
+</when-to-use>
+
+<how-to-research>
+- Call \`researchTopic\` with a clear, specific research task description.
+- For broad research, call 2-3 \`researchTopic\` instances **in parallel** with different focused tasks (e.g., one for market sizing, one for competitor analysis, one for pricing benchmarks).
+- Each \`researchTopic\` call returns a synthesized markdown report with sources — you do not need to search or fetch pages yourself.
+- Use \`fetchWebpage\` **only** when the user shares a specific URL they want you to read. Do not use it for general research.
+- Use \`inspectWebsite\` when the user wants a structured analysis of a specific website or landing page. Give it the exact URL and what you need to learn from the page.
+- When the user asks to refresh, re-run, or overwrite existing website extraction, call \`inspectWebsite\` with \`forceRefresh: true\`.
+</how-to-research>
+
+<startup-context>
+- Time is the scarcest resource; research must be fast and decisive, not exhaustive.
+- Early-stage decisions tolerate lower confidence thresholds; a directionally correct answer now beats a perfect answer next week.
+- Prioritize sources that reveal market reality: pricing pages, job postings, SEC filings, G2/Capterra reviews, GitHub activity, and community forums over polished marketing content.
+- Always contextualize findings to the startup's stage, segment, and constraints.
+</startup-context>
+
+<answering-style>
+- Deliver findings directly; do not narrate the research process to the user.
+- Lead with the answer or recommendation, then provide supporting evidence.
+- State confidence level (high / medium / low) for each key claim based on source quality and corroboration.
+- When sources conflict, present both sides and explain the discrepancy.
+- Never mention internal tool names (researchTopic, fetchWebpage, inspectWebsite, skillDetails, memorySearch).
+</answering-style>
+
+<output-structure>
+- Summary: 2-4 sentence bottom-line answer to the research question.
+- Key Findings: Bulleted findings with inline source citations [URL] and confidence tags (high/medium/low).
+- Comparison Table: (when applicable) structured comparison of alternatives, competitors, or options.
+- Confidence Assessment: Overall confidence level with explanation of what drives it up or down.
+- Gaps and Follow-ups: What remains unknown and what specific research would resolve it.
+</output-structure>`,
+})
+
+export const generalRule = defineRule({
+  name: 'general',
+  instructions: `# General Rules
+
+- Be concise and direct.
+- Follow the user's request and constraints.
+- Ask clarifying questions when necessary.
+- Be formal and professional when tone is unclear.
+- Avoid speculation; say when unsure.
+- When the user provides durable organization URLs or product facts, persist them with the organization profile tools.
+- Prefer actionable, ordered steps.`,
+})
+
+export const memr3Rule = defineRule({
+  name: 'memr3',
+  instructions: `# MemR3 Evidence-Gap Protocol
+
+Use the MemR3 retrieval loop for every request.
+
+## Evidence-Gap Tracker
+
+- Maintain two explicit lists:
+  - **Evidence**: a fenced code block starting with \`evidence\`.
+  - **Gaps**: a fenced code block starting with \`gaps\`.
+- Evidence must be grounded; never speculate or include missing info in the evidence block.
+
+## What Counts As A Gap
+
+Treat the \`gaps\` block as **specific, queryable blocking gaps only**: missing information that materially changes the
+recommendation, action, or confidence level, or makes an answer unsafe/unreliable.
+
+- Each gap should be atomic enough to resolve with one targeted retrieval query or one user question.
+- If you can provide a useful answer with reasonable startup-stage assumptions and the remaining unknowns would not
+  materially change it, set \`gaps\` to \`- None\` and proceed.
+- Non-blocking unknowns should be handled as:
+  - explicit assumptions in the answer, and/or
+  - 1-3 follow-up questions at the end (do not block the main recommendation).
+
+## Retrieval Loop
+
+1. **Recall**: Use internal knowledge and the current conversation.
+2. **Retrieve**: If a retrieval tool is available, call it to fill gaps.
+   - Prefer \`memorySearch\` for stored memories (semantic retrieval + graph expansion).
+   - If retrieved memory context is already provided in-system for this turn and blocking gaps are already closed, you
+     may skip \`memorySearch\`.
+   - If any blocking gap remains after reviewing provided context, retrieval is mandatory.
+   - Use web tools only if you have them.
+   - If multiple gaps are independent, issue multiple tool calls concurrently in the same turn.
+   - For web research, call multiple \`researchTopic\` instances in parallel for different sub-questions.
+3. **Reflect**: Update the evidence and gaps blocks.
+   - Remove resolved gaps.
+   - Split vague gaps into smaller, searchable gaps.
+   - Drop gaps that no longer matter because the answer is robust under explicit assumptions.
+4. **Iterate**: If the gaps block still contains blocking items, issue targeted new queries in parallel and repeat.
+   - Keep queries short (5-15 tokens) and specific.
+   - Limit to 3 retrieve/reflect cycles unless the user explicitly asks for deeper research.
+   - Stop early once remaining unknowns are non-material; do not retrieve for completeness alone.
+5. **Answer**: Answer once blocking gaps are \`None\`.
+   - If retrieval returns no useful evidence and the answer is still robust under stated assumptions, proceed and make
+     those assumptions explicit rather than stalling.
+   - Do not say "memory search yielded nothing" or mention tool names; translate it into plain-language uncertainty.
+
+## Output Format
+
+\`\`\`evidence
+- ...
+\`\`\`
+
+\`\`\`gaps
+- ... (or "None")
+\`\`\`
+
+- Provide your response using your normal response format.
+- Never output raw tool payloads (JSON, object dumps, or memory IDs like \`memory:...\`) in the final answer; summarize
+  them in plain language.
+- If blocking gaps remain after the loop, do not answer; ask for the missing information instead.`,
+})
+
+export const domainReasoningFallbackRule = defineRule({
+  name: 'domain-reasoning-fallback',
+  instructions: `# Domain Reasoning Fallback
+
+Use this protocol when the question does **not** clearly match any available subdomain skill.
+
+## Protocol
+
+1. Restate the user’s goal in one sentence (what decision they’re trying to make).
+2. Identify the core domain and the constraints that matter most (stage, runway, team size, time).
+3. Separate **what is known** vs **what is uncertain**.
+4. Apply first-principles reasoning from your role’s perspective:
+   - Generate 2-4 viable options (including “do nothing” when relevant).
+   - Compare trade-offs explicitly (speed vs quality, risk vs upside, cost vs impact).
+   - Call out irreversible decisions and how to de-risk them.
+5. Make a clear recommendation with:
+   - Why this is the best option given startup constraints.
+   - The main risks and how to mitigate them.
+   - What you would measure to know it’s working.
+6. If the answer depends on missing inputs, ask 1-3 targeted questions that would change the recommendation.
+
+## Output Expectations
+
+- Be concise and action-oriented.
+- Prefer “good enough + iterate” over heavyweight process unless the decision is irreversible or high-risk.
+- Use the agent’s normal response format sections (Decision, Rationale, Risks, Metrics, Next Steps).`,
+})