@lota-sdk/core 0.4.8 → 0.4.10

package/src/services/learned-skill.service.ts

@@ -1,28 +1,25 @@
 import { recordIdStringSchema } from '@lota-sdk/shared'
+import { Cache, Context, Schema, Duration, Effect, Layer } from 'effect'
 import { BoundQuery } from 'surrealdb'
 import { z } from 'zod'
 
 import { renderLearnedSkillInstructions } from '../ai/definitions'
-import { lotaDebugLogger } from '../config/debug-logger'
 import { serverLogger } from '../config/logger'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
-import { databaseService } from '../db/service'
+import type { SurrealDBService } from '../db/service'
 import { TABLES } from '../db/tables'
-import { getDefaultEmbeddings } from '../embeddings/provider'
-import { getRedisConnection } from '../redis'
-
-const embeddings = getDefaultEmbeddings()
+import { makeEffectTryPromiseWithMessage } from '../effect/helpers'
+import { DatabaseServiceTag, RuntimeConfigServiceTag } from '../effect/services'
+import { ProviderEmbeddings } from '../embeddings/provider'
+import { sha256HexFromParts } from '../utils/crypto'
+import { nowDate } from '../utils/date-time'
+import { BackgroundWorkService } from './background-work.service'
 
 const PROMOTION_MIN_USES = 5
 const PROMOTION_MIN_SUCCESS_RATE = 0.6
 
 const ACTIVE_SKILL_FILTER = "AND status IN ['learned', 'verified', 'promoted'] AND archivedAt IS NONE"
 const SKILL_EXISTS_TTL_SECONDS = 120
-const SKILL_EXISTS_KEY_PREFIX = 'skill-exists'
-
-function skillExistsKey(orgId: string, agentId: string): string {
-  return `${SKILL_EXISTS_KEY_PREFIX}:${orgId}:${agentId}`
-}
 
 const LearnedSkillRowSchema = z.object({
   id: recordIdStringSchema,
@@ -59,7 +56,26 @@ const SearchResultRowSchema = z.object({
   similarity: z.number(),
 })
 
-type SearchResultRow = z.infer<typeof SearchResultRowSchema>
+class LearnedSkillServiceError extends Schema.TaggedErrorClass<LearnedSkillServiceError>()('LearnedSkillServiceError', {
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+class LearnedSkillNotFoundError extends Schema.TaggedErrorClass<LearnedSkillNotFoundError>()(
+  'LearnedSkillNotFoundError',
+  { message: Schema.String },
+) {}
+
+const effectTryLearnedSkillPromise = makeEffectTryPromiseWithMessage(
+  (message, cause) => new LearnedSkillServiceError({ message, cause }),
+)
+
+function tryLearnedSkillPromise<A>(
+  message: string,
+  evaluate: () => PromiseLike<A> | Effect.Effect<A, unknown>,
+): Effect.Effect<A, LearnedSkillServiceError> {
+  return effectTryLearnedSkillPromise(evaluate, message)
+}
 
 interface CreateLearnedSkillInput {
   name: string
@@ -98,124 +114,102 @@ interface RetrieveForTurnParams {
   minConfidence: number
 }
 
-class LearnedSkillService {
-  async create(input: CreateLearnedSkillInput): Promise<LearnedSkillRow> {
-    const orgRef = ensureRecordId(input.organizationId, TABLES.ORGANIZATION)
-
-    const data: Record<string, unknown> = {
-      name: input.name,
-      description: input.description,
-      instructions: input.instructions,
-      triggers: input.triggers,
-      tags: input.tags,
-      examples: input.examples,
-      sourceType: input.sourceType,
-      organizationId: orgRef,
-      agentId: input.agentId,
-      confidence: input.confidence,
-      embedding: input.embedding,
-      hash: input.hash,
-    }
-
-    const result = await databaseService.create(TABLES.LEARNED_SKILL, data, LearnedSkillRowSchema)
-    await this.invalidateSkillExistsCache(input.organizationId, input.agentId)
-    return result
-  }
-
-  async update(skillId: string, input: UpdateLearnedSkillInput): Promise<LearnedSkillRow> {
-    const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
-    const data: Record<string, unknown> = {}
-
-    if (input.name !== undefined) data.name = input.name
-    if (input.description !== undefined) data.description = input.description
-    if (input.instructions !== undefined) data.instructions = input.instructions
-    if (input.triggers !== undefined) data.triggers = input.triggers
-    if (input.tags !== undefined) data.tags = input.tags
-    if (input.examples !== undefined) data.examples = input.examples
-    if (input.confidence !== undefined) data.confidence = input.confidence
-    if (input.version !== undefined) data.version = input.version
-    if (input.embedding !== undefined) data.embedding = input.embedding
-    if (input.hash !== undefined) data.hash = input.hash
-    if (input.supersedes !== undefined) data.supersedes = ensureRecordId(input.supersedes, TABLES.LEARNED_SKILL)
-
-    const updated = await databaseService.update(TABLES.LEARNED_SKILL, ref, data, LearnedSkillRowSchema)
-    if (!updated) throw new Error(`Learned skill ${skillId} not found`)
-    return updated
-  }
-
-  async archive(skillId: string): Promise<void> {
-    const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
-    const skill = await this.getById(skillId)
-    await databaseService.update(
-      TABLES.LEARNED_SKILL,
-      ref,
-      { status: 'archived', archivedAt: new Date() },
-      LearnedSkillRowSchema,
-    )
-    if (skill) {
-      await this.invalidateSkillExistsCache(recordIdToString(skill.organizationId), skill.agentId ?? null)
-    }
-  }
-
-  async getById(skillId: string): Promise<LearnedSkillRow | null> {
-    return databaseService.findOne(
-      TABLES.LEARNED_SKILL,
-      { id: ensureRecordId(skillId, TABLES.LEARNED_SKILL) },
-      LearnedSkillRowSchema,
-    )
-  }
-
-  private async hasSkillsForAgent(orgId: string, agentId: string): Promise<boolean> {
-    const redis = getRedisConnection()
-    const key = skillExistsKey(orgId, agentId)
-
-    const cached = await redis.get(key)
-    if (cached !== null) return cached === '1'
-
-    const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
-    const rows = await databaseService.query<{ id: unknown }>(
-      new BoundQuery(
-        `SELECT id FROM ${TABLES.LEARNED_SKILL}
-         WHERE organizationId = $orgRef
-           ${ACTIVE_SKILL_FILTER}
-           AND (agentId IS NONE OR agentId = $agentId)
-         LIMIT 1`,
-        { orgRef, agentId },
-      ),
+export function makeLearnedSkillService(
+  db: SurrealDBService,
+  options: { embeddingModel: string; openRouterApiKey?: string },
+  skillExistsCache: Cache.Cache<string, boolean, LearnedSkillServiceError>,
+  background: Context.Service.Shape<typeof BackgroundWorkService>,
+) {
+  const embeddings = new ProviderEmbeddings({
+    modelId: options.embeddingModel,
+    openRouterApiKey: options.openRouterApiKey,
+  })
+
+  const hasSkillsForAgent = (orgId: string, agentId: string) => Cache.get(skillExistsCache, `${orgId}:${agentId}`)
+
+  const invalidateSkillExistsCache = (orgId: string, agentId: string | null) =>
+    Effect.gen(function* () {
+      const keys = yield* Cache.keys(skillExistsCache)
+      const orgPrefix = `${orgId}:`
+      const matchingKeys = [...keys].filter((key) => key.startsWith(orgPrefix))
+      if (matchingKeys.length > 0) {
+        yield* Effect.forEach(matchingKeys, (key) => Cache.invalidate(skillExistsCache, key))
+      }
+      if (agentId) {
+        yield* Cache.set(skillExistsCache, `${orgId}:${agentId}`, true)
+      }
+    })
+
+  const create = (input: CreateLearnedSkillInput) =>
+    Effect.gen(function* () {
+      const orgRef = ensureRecordId(input.organizationId, TABLES.ORGANIZATION)
+
+      const data: Record<string, unknown> = {
+        name: input.name,
+        description: input.description,
+        instructions: input.instructions,
+        triggers: input.triggers,
+        tags: input.tags,
+        examples: input.examples,
+        sourceType: input.sourceType,
+        organizationId: orgRef,
+        agentId: input.agentId,
+        confidence: input.confidence,
+        embedding: input.embedding,
+        hash: input.hash,
+      }
+
+      const result = yield* tryLearnedSkillPromise('Failed to create learned skill.', () =>
+        db.create(TABLES.LEARNED_SKILL, data, LearnedSkillRowSchema),
+      )
+      yield* invalidateSkillExistsCache(input.organizationId, input.agentId)
+      return result
+    })
+
+  const update = (skillId: string, input: UpdateLearnedSkillInput) =>
+    Effect.gen(function* () {
+      const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
+      const data: Record<string, unknown> = {}
+
+      if (input.name !== undefined) data.name = input.name
+      if (input.description !== undefined) data.description = input.description
+      if (input.instructions !== undefined) data.instructions = input.instructions
+      if (input.triggers !== undefined) data.triggers = input.triggers
+      if (input.tags !== undefined) data.tags = input.tags
+      if (input.examples !== undefined) data.examples = input.examples
+      if (input.confidence !== undefined) data.confidence = input.confidence
+      if (input.version !== undefined) data.version = input.version
+      if (input.embedding !== undefined) data.embedding = input.embedding
+      if (input.hash !== undefined) data.hash = input.hash
+      if (input.supersedes !== undefined) data.supersedes = ensureRecordId(input.supersedes, TABLES.LEARNED_SKILL)
+
+      const updated = yield* tryLearnedSkillPromise(`Failed to update learned skill ${skillId}.`, () =>
+        db.update(TABLES.LEARNED_SKILL, ref, data, LearnedSkillRowSchema),
+      )
+      if (!updated) {
+        return yield* new LearnedSkillNotFoundError({ message: `Learned skill ${skillId} not found` })
+      }
+      return updated
+    })
+
+  const archive = (skillId: string) =>
+    Effect.gen(function* () {
+      const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
+      const skill = yield* getById(skillId)
+      yield* tryLearnedSkillPromise(`Failed to archive learned skill ${skillId}.`, () =>
+        db.update(TABLES.LEARNED_SKILL, ref, { status: 'archived', archivedAt: nowDate() }, LearnedSkillRowSchema),
+      )
+      if (skill) {
+        yield* invalidateSkillExistsCache(recordIdToString(skill.organizationId), skill.agentId ?? null)
+      }
+    })
+
+  const getById = (skillId: string): Effect.Effect<LearnedSkillRow | null, LearnedSkillServiceError> =>
+    tryLearnedSkillPromise(`Failed to load learned skill ${skillId}.`, () =>
+      db.findOne(TABLES.LEARNED_SKILL, { id: ensureRecordId(skillId, TABLES.LEARNED_SKILL) }, LearnedSkillRowSchema),
     )
 
-    const exists = rows.length > 0
-    await redis.set(key, exists ? '1' : '0', 'EX', SKILL_EXISTS_TTL_SECONDS)
-    return exists
-  }
-
-  private async invalidateSkillExistsCache(orgId: string, agentId: string | null): Promise<void> {
-    const redis = getRedisConnection()
-    const pattern = `${SKILL_EXISTS_KEY_PREFIX}:${orgId}:*`
-    const keys = await redis.keys(pattern)
-    if (keys.length > 0) {
-      await redis.del(...keys)
-    }
-    // Also set the specific key if we know a skill was just created
-    if (agentId) {
-      await redis.set(skillExistsKey(orgId, agentId), '1', 'EX', SKILL_EXISTS_TTL_SECONDS)
-    }
-  }
-
-  async searchForTurn(params: RetrieveForTurnParams): Promise<SearchResultRow[]> {
-    const timer = lotaDebugLogger.timer('learned-skills')
-
-    const hasSkills = await this.hasSkillsForAgent(params.orgId, params.agentId)
-    if (!hasSkills) {
-      lotaDebugLogger.step('learned-skills: skipped — no skills for org+agent')
-      return []
-    }
-    timer.step('has-skills-check')
-
-    const queryEmbedding = await embeddings.embedQuery(params.query)
-    timer.step('embed-query')
-    if (queryEmbedding.length === 0) return []
-
+  const searchForTurn = Effect.fn('LearnedSkillService.searchForTurn')(function* (params: RetrieveForTurnParams) {
     const orgRef = ensureRecordId(params.orgId, TABLES.ORGANIZATION)
     const sql = `
       SELECT
@@ -234,153 +228,267 @@ class LearnedSkillService {
       ORDER BY similarity DESC
     `
 
-    const rows = await databaseService.query<unknown>(
-      new BoundQuery(sql, {
-        organizationId: orgRef,
-        embedding: queryEmbedding,
-        agentId: params.agentId,
-        minConfidence: params.minConfidence,
-      }),
+    const hasSkills = yield* hasSkillsForAgent(params.orgId, params.agentId).pipe(
+      Effect.withSpan('LearnedSkillService.checkSkillsAvailability'),
     )
-    timer.step('knn-query')
+    yield* Effect.annotateCurrentSpan({
+      orgId: params.orgId,
+      agentId: params.agentId,
+      limit: params.limit,
+      minConfidence: params.minConfidence,
+      skillsAvailable: hasSkills,
+    })
+    if (!hasSkills) {
+      return []
+    }
 
-    return rows.map((row) => SearchResultRowSchema.parse(row)).filter((row) => row.similarity >= 0.3)
-  }
+    const queryEmbedding = yield* tryLearnedSkillPromise('Failed to embed learned skill query.', () =>
+      embeddings.embedQuery(params.query),
+    ).pipe(Effect.withSpan('LearnedSkillService.embedQuery'))
+    yield* Effect.annotateCurrentSpan('embeddingLength', queryEmbedding.length)
+    if (queryEmbedding.length === 0) return []
 
-  async retrieveForTurn(params: RetrieveForTurnParams): Promise<string | undefined> {
-    const results = await this.searchForTurn(params)
+    const rows = yield* tryLearnedSkillPromise('Failed to query learned skills.', () =>
+      db.query<unknown>(
+        new BoundQuery(sql, {
+          organizationId: orgRef,
+          embedding: queryEmbedding,
+          agentId: params.agentId,
+          minConfidence: params.minConfidence,
+        }),
+      ),
+    ).pipe(Effect.withSpan('LearnedSkillService.queryNearestSkills'))
+    const parsedRows = yield* Effect.try({
+      try: () => rows.map((row) => SearchResultRowSchema.parse(row)),
+      catch: (cause) =>
+        new LearnedSkillServiceError({ message: 'Failed to parse learned skill search results.', cause }),
+    })
+    return parsedRows.filter((row) => row.similarity >= 0.3)
+  })
+
+  const retrieveForTurn = Effect.fn('LearnedSkillService.retrieveForTurn')(function* (params: RetrieveForTurnParams) {
+    const results = yield* searchForTurn(params)
     if (results.length === 0) return undefined
 
-    for (const result of results) {
-      void this.recordUsage(result.id).catch((error) => {
-        serverLogger.warn`Failed to record learned skill usage for ${result.id}: ${error}`
-      })
-    }
+    yield* background.run(
+      Effect.forEach(
+        results,
+        (result) =>
+          recordUsage(result.id).pipe(
+            Effect.tapError((error) =>
+              Effect.sync(() => {
+                serverLogger.warn`Failed to record learned skill usage for ${result.id}: ${error}`
+              }),
+            ),
+          ),
+        { discard: true },
+      ),
+      'learned-skill.recordUsage',
+    )
 
     const section = renderLearnedSkillInstructions(
       results.map((row) => ({ name: row.name, instructions: row.instructions })),
     )
     return section || undefined
-  }
-
-  async recordUsage(skillId: string): Promise<void> {
-    const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
-    await databaseService.query<unknown>(
-      new BoundQuery(`UPDATE ${TABLES.LEARNED_SKILL} SET usageCount += 1, lastUsedAt = time::now() WHERE id = $id`, {
-        id: ref,
-      }),
-    )
-  }
-
-  async recordSuccess(skillId: string): Promise<void> {
-    const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
-    await databaseService.query<unknown>(
-      new BoundQuery(`UPDATE ${TABLES.LEARNED_SKILL} SET successCount += 1 WHERE id = $id`, { id: ref }),
-    )
-  }
-
-  async promoteIfEligible(skillId: string): Promise<boolean> {
-    const skill = await this.getById(skillId)
-    if (!skill) return false
-    if (skill.status !== 'learned') return false
-    if (skill.usageCount < PROMOTION_MIN_USES) return false
-
-    const successRate = skill.successCount / skill.usageCount
-    if (successRate < PROMOTION_MIN_SUCCESS_RATE) return false
-
-    const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
-    await databaseService.update(
-      TABLES.LEARNED_SKILL,
-      ref,
-      { status: 'verified', confidence: Math.min(skill.confidence + 0.1, 1.0) },
-      LearnedSkillRowSchema,
-    )
-    return true
-  }
-
-  async findMostSimilar(orgId: string, description: string): Promise<LearnedSkillRow | null> {
-    const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
-    const descEmbedding = await embeddings.embedQuery(description)
-    if (descEmbedding.length === 0) return null
-
-    const sql = `
-      SELECT *,
-        type::string(id) AS id,
-        type::string(organizationId) AS organizationId,
-        vector::similarity::cosine(embedding, $embedding) AS similarity
-      FROM ${TABLES.LEARNED_SKILL}
-      WHERE organizationId = $organizationId
-        ${ACTIVE_SKILL_FILTER}
-        AND embedding <|3|> $embedding
-      ORDER BY similarity DESC
-      LIMIT 1
-    `
-
-    const rows = await databaseService.query<unknown>(
-      new BoundQuery(sql, { organizationId: orgRef, embedding: descEmbedding }),
-    )
-
-    if (rows.length === 0) return null
-    return LearnedSkillRowSchema.parse(rows[0])
-  }
-
-  async listForOrg(orgId: string): Promise<LearnedSkillRow[]> {
-    const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
-    return databaseService.queryMany(
-      new BoundQuery(
-        `SELECT *, type::string(id) AS id, type::string(organizationId) AS organizationId
-         FROM ${TABLES.LEARNED_SKILL}
-         WHERE organizationId = $organizationId
-           ${ACTIVE_SKILL_FILTER}
-         ORDER BY createdAt DESC`,
-        { organizationId: orgRef },
+  })
+
+  const recordUsage = (skillId: string) =>
+    Effect.gen(function* () {
+      const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
+      yield* tryLearnedSkillPromise(`Failed to record usage for learned skill ${skillId}.`, () =>
+        db.query<unknown>(
+          new BoundQuery(
+            `UPDATE ${TABLES.LEARNED_SKILL} SET usageCount += 1, lastUsedAt = time::now() WHERE id = $id`,
+            { id: ref },
+          ),
+        ),
+      )
+    })
+
+  const recordSuccess = (skillId: string) =>
+    Effect.gen(function* () {
+      const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
+      yield* tryLearnedSkillPromise(`Failed to record success for learned skill ${skillId}.`, () =>
+        db.query<unknown>(
+          new BoundQuery(`UPDATE ${TABLES.LEARNED_SKILL} SET successCount += 1 WHERE id = $id`, { id: ref }),
+        ),
+      )
+    })
+
+  const promoteIfEligible = (skillId: string) =>
+    Effect.gen(function* () {
+      const skill = yield* getById(skillId)
+      if (!skill) return false
+      if (skill.status !== 'learned') return false
+      if (skill.usageCount < PROMOTION_MIN_USES) return false
+
+      const successRate = skill.successCount / skill.usageCount
+      if (successRate < PROMOTION_MIN_SUCCESS_RATE) return false
+
+      const ref = ensureRecordId(skillId, TABLES.LEARNED_SKILL)
+      yield* tryLearnedSkillPromise(`Failed to promote learned skill ${skillId}.`, () =>
+        db.update(
+          TABLES.LEARNED_SKILL,
+          ref,
+          { status: 'verified', confidence: Math.min(skill.confidence + 0.1, 1.0) },
+          LearnedSkillRowSchema,
+        ),
+      )
+      return true
+    })
+
+  const findMostSimilar = (orgId: string, description: string) =>
+    Effect.gen(function* () {
+      const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
+      const sql = `
+        SELECT *,
+          type::string(id) AS id,
+          type::string(organizationId) AS organizationId,
+          vector::similarity::cosine(embedding, $embedding) AS similarity
+        FROM ${TABLES.LEARNED_SKILL}
+        WHERE organizationId = $organizationId
+          ${ACTIVE_SKILL_FILTER}
+          AND embedding <|3|> $embedding
+        ORDER BY similarity DESC
+        LIMIT 1
+      `
+
+      const descEmbedding = yield* tryLearnedSkillPromise('Failed to embed learned skill description.', () =>
+        embeddings.embedQuery(description),
+      )
+      if (descEmbedding.length === 0) return null
+
+      const rows = yield* tryLearnedSkillPromise('Failed to query most similar learned skill.', () =>
+        db.query<unknown>(new BoundQuery(sql, { organizationId: orgRef, embedding: descEmbedding })),
+      )
+      if (rows.length === 0) return null
+      return yield* Effect.try({
+        try: () => LearnedSkillRowSchema.parse(rows[0]),
+        catch: (cause) =>
+          new LearnedSkillServiceError({ message: 'Failed to parse most similar learned skill row.', cause }),
+      })
+    })
+
+  const listForOrg = (orgId: string) =>
+    tryLearnedSkillPromise(`Failed to list learned skills for organization ${orgId}.`, () =>
+      db.queryMany(
+        new BoundQuery(
+          `SELECT *, type::string(id) AS id, type::string(organizationId) AS organizationId
+           FROM ${TABLES.LEARNED_SKILL}
+           WHERE organizationId = $organizationId
+             ${ACTIVE_SKILL_FILTER}
+           ORDER BY createdAt DESC`,
+          { organizationId: ensureRecordId(orgId, TABLES.ORGANIZATION) },
+        ),
+        LearnedSkillRowSchema,
       ),
-      LearnedSkillRowSchema,
     )
-  }
 
-  generateHash(description: string, instructions: string): string {
-    const hasher = new Bun.CryptoHasher('sha256')
-    hasher.update(description.trim().toLowerCase())
-    hasher.update(instructions.trim().toLowerCase())
-    return hasher.digest('hex')
+  const findByNameOrTag = (orgId: string, nameOrTag: string) =>
+    Effect.gen(function* () {
+      const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
+      const normalizedRef = nameOrTag.trim().toLowerCase()
+      const rows = yield* tryLearnedSkillPromise(`Failed to find learned skill by name or tag for org ${orgId}.`, () =>
+        db.queryMany(
+          new BoundQuery(
+            `SELECT *, type::string(id) AS id, type::string(organizationId) AS organizationId
+           FROM ${TABLES.LEARNED_SKILL}
+           WHERE organizationId = $organizationId
+             ${ACTIVE_SKILL_FILTER}
+             AND (string::lowercase(name) = $nameRef OR $nameRef IN tags)
+           ORDER BY confidence DESC
+           LIMIT 1`,
+            { organizationId: orgRef, nameRef: normalizedRef },
+          ),
+          LearnedSkillRowSchema,
+        ),
+      )
+      return rows[0] ?? null
+    })
+
+  const findByHash = (orgId: string, hash: string): Effect.Effect<LearnedSkillRow | null, LearnedSkillServiceError> =>
+    Effect.gen(function* () {
+      const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
+      const rows = yield* tryLearnedSkillPromise(`Failed to find learned skill by hash for org ${orgId}.`, () =>
+        db.queryMany(
+          new BoundQuery(
+            `SELECT *, type::string(id) AS id, type::string(organizationId) AS organizationId
+           FROM ${TABLES.LEARNED_SKILL}
+           WHERE organizationId = $organizationId
+             AND hash = $hash
+             ${ACTIVE_SKILL_FILTER}
+             LIMIT 1`,
+            { organizationId: orgRef, hash },
+          ),
+          LearnedSkillRowSchema,
+        ),
+      )
+      return rows[0] ?? null
+    })
+
+  function generateHash(description: string, instructions: string): string {
+    return sha256HexFromParts([description.trim().toLowerCase(), instructions.trim().toLowerCase()])
   }
 
-  async findByNameOrTag(orgId: string, nameOrTag: string): Promise<LearnedSkillRow | null> {
-    const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
-    const normalizedRef = nameOrTag.trim().toLowerCase()
-    const rows = await databaseService.queryMany(
-      new BoundQuery(
-        `SELECT *, type::string(id) AS id, type::string(organizationId) AS organizationId
-         FROM ${TABLES.LEARNED_SKILL}
-         WHERE organizationId = $organizationId
-           ${ACTIVE_SKILL_FILTER}
-           AND (string::lowercase(name) = $nameRef OR $nameRef IN tags)
-         ORDER BY confidence DESC
-         LIMIT 1`,
-        { organizationId: orgRef, nameRef: normalizedRef },
-      ),
-      LearnedSkillRowSchema,
-    )
-    return rows[0] ?? null
-  }
-
-  async findByHash(orgId: string, hash: string): Promise<LearnedSkillRow | null> {
-    const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
-    const rows = await databaseService.queryMany(
-      new BoundQuery(
-        `SELECT *, type::string(id) AS id, type::string(organizationId) AS organizationId
-         FROM ${TABLES.LEARNED_SKILL}
-         WHERE organizationId = $organizationId
-           AND hash = $hash
-           ${ACTIVE_SKILL_FILTER}
-         LIMIT 1`,
-        { organizationId: orgRef, hash },
-      ),
-      LearnedSkillRowSchema,
-    )
-    return rows[0] ?? null
+  return {
+    create,
+    update,
+    archive,
+    getById,
+    searchForTurn,
+    retrieveForTurn,
+    recordUsage,
+    recordSuccess,
+    promoteIfEligible,
+    findMostSimilar,
+    listForOrg,
+    generateHash,
+    findByNameOrTag,
+    findByHash,
   }
 }
 
-export const learnedSkillService = new LearnedSkillService()
+export class LearnedSkillServiceTag extends Context.Service<
+  LearnedSkillServiceTag,
+  ReturnType<typeof makeLearnedSkillService>
+>()('@lota-sdk/core/LearnedSkillService') {}
+
+export const LearnedSkillServiceLive = Layer.effect(
+  LearnedSkillServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    const runtimeConfig = yield* RuntimeConfigServiceTag
+    const background = yield* BackgroundWorkService
+    const skillExistsCache = yield* Cache.make({
+      lookup: (key: string) =>
+        Effect.gen(function* () {
+          const [orgId, agentId] = key.split(':', 2) as [string, string]
+          const orgRef = ensureRecordId(orgId, TABLES.ORGANIZATION)
+          const rows = yield* tryLearnedSkillPromise('Failed to check learned skill existence cache.', () =>
+            db.query<{ id: unknown }>(
+              new BoundQuery(
+                `SELECT id FROM ${TABLES.LEARNED_SKILL}
+                 WHERE organizationId = $orgRef
+                   ${ACTIVE_SKILL_FILTER}
+                   AND (agentId IS NONE OR agentId = $agentId)
+                 LIMIT 1`,
+                { orgRef, agentId },
+              ),
+            ),
+          )
+          return rows.length > 0
+        }),
+      capacity: 256,
+      timeToLive: Duration.seconds(SKILL_EXISTS_TTL_SECONDS),
+    })
+    return makeLearnedSkillService(
+      db,
+      {
+        embeddingModel: runtimeConfig.aiGateway.embeddingModel,
+        openRouterApiKey: runtimeConfig.aiGateway.openRouterApiKey,
+      },
+      skillExistsCache,
+      background,
+    )
+  }),
+)