@raybase/core 0.0.2 → 0.3.3

package/dist/agent-skill-store.js

@@ -0,0 +1,514 @@
+import { RaybaseActionError } from "./actions.js";
+import { agentSkillRegistrations } from "./agent-skills.js";
+import { recordAudit } from "./audit.js";
+import { normalizeSkillPath, validateOpenAgentSkillName } from "./agent-skill-format.js";
+import { sha256Hex, stableJson } from "./internal.js";
+import { id, integer, longText, raybaseSystemTable, text } from "./schema.js";
+import { nowIso, q, randomId } from "./sql.js";
+import { validateOutboundHttpsUrl, validateOutboundOrigin } from "./outbound-https.js";
+export const raybaseAgentSkillStoreLimits = {
+    maxSkills: 200,
+    maxSkillsCap: 1000,
+    maxGuidanceBytes: 64_000,
+    maxGuidanceBytesCap: 256_000,
+    uploadBytes: 10 * 1024 * 1024,
+    uploadInlineBytes: 1024 * 1024,
+    uploadTtlMs: 15 * 60 * 1000,
+    revisionsPerSkill: 3
+};
+export const raybaseAgentSkillToolNames = [
+    "skill_list", "skill_read", "skill_write", "skill_edit", "skill_delete", "skill_set_enabled",
+    "skill_import_discover", "skill_import_apply"
+];
+export const raybaseAgentSkillSystemTables = [
+    raybaseSystemTable("_agent_skills", {
+        id: id(), agentName: text({ required: true }), normalizedName: text({ required: true }), name: text({ required: true }), title: text(),
+        description: text({ required: true }), guidance: longText({ required: true }), mode: text({ required: true }), ephemeral: integer({ required: true }), contentDigest: text({ required: true }),
+        lastImportedContentDigest: text(), license: text(), compatibility: text(), metadataJson: longText({ required: true }), enabled: integer({ required: true }),
+        revision: integer({ required: true }), source: text({ required: true }), ownerKind: text({ required: true }), ownerAgentName: text(), createdBy: text({ required: true }),
+        originKind: text({ required: true }), originUrl: text(), originRef: text(), originRefKind: text(), originCommit: text(), originRepo: text(),
+        originManifestPath: text(), originSkillPath: text(), originDigest: text(), importedAt: text(), sourceId: text(), remoteSha256: text(), syncedAt: text(),
+        syncStatus: text(), syncError: longText(), createdAt: text({ required: true }), updatedAt: text({ required: true })
+    }, { indexes: [{ columns: ["agentName", "normalizedName"], unique: true }, ["agentName", "enabled"], ["sourceId"], ["updatedAt"]] }),
+    raybaseSystemTable("_agent_skill_files", {
+        id: id(), skillId: text({ required: true }), path: text({ required: true }), normalizedPath: text({ required: true }), kind: text({ required: true }),
+        encoding: text({ required: true }), content: longText({ required: true }), bytes: integer({ required: true }), sha256: text({ required: true }), createdAt: text({ required: true })
+    }, { indexes: [{ columns: ["skillId", "normalizedPath"], unique: true }, ["skillId"]] }),
+    raybaseSystemTable("_agent_skill_sources", {
+        id: id(), agentName: text({ required: true }), sourceType: text({ required: true }), url: text({ required: true }), registeredBy: text({ required: true }),
+        enabled: integer({ required: true }), revision: integer({ required: true }), syncEveryMs: integer({ required: true }), authSecretName: text(), allowedArtifactOriginsJson: longText({ required: true }),
+        artifactAuthJson: longText({ required: true }), selectionMode: text({ required: true }), selectedNamesJson: longText({ required: true }), etag: text(),
+        lastSyncAt: text(), lastSyncStatus: text(), lastSyncError: longText(), lastSyncSummaryJson: longText(), repo: text(), manifestPath: text(), requestedRef: text(),
+        refKind: text(), defaultBranch: text(), resolvedCommit: text(), createdAt: text({ required: true }), updatedAt: text({ required: true })
+    }, { indexes: [{ columns: ["agentName", "url"], unique: true }, ["enabled", "lastSyncAt"], ["agentName"]] }),
+    raybaseSystemTable("_agent_skill_revisions", {
+        id: id(), skillId: text({ required: true }), revision: integer({ required: true }), title: text(), description: text({ required: true }),
+        guidance: longText({ required: true }), mode: text({ required: true }), ephemeral: integer({ required: true }), enabled: integer({ required: true }), contentDigest: text({ required: true }),
+        reason: text({ required: true }), actorKind: text({ required: true }), actor: text(), createdAt: text({ required: true })
+    }, { indexes: [["skillId", "revision"], ["createdAt"]] }),
+    raybaseSystemTable("_agent_skill_uploads", {
+        id: id(), agentName: text({ required: true }), filename: text({ required: true }), contentBase64: longText({ required: true }), bytes: integer({ required: true }),
+        sha256: text({ required: true }), createdByUserId: text(), createdAt: text({ required: true }), expiresAt: text({ required: true })
+    }, { indexes: [["agentName", "createdAt"], ["expiresAt"]] }),
+    raybaseSystemTable("_agent_skill_loads", {
+        id: id(), conversationId: text({ required: true }), chapterId: text({ required: true }), skillName: text({ required: true }), loadedAt: text({ required: true })
+    }, { indexes: [{ columns: ["conversationId", "chapterId", "skillName"], unique: true }, ["conversationId", "chapterId"]] })
+];
+export function validateAgentSkillStoreForAgent(agent) {
+    const store = agent.skillStore;
+    if (store === undefined)
+        return;
+    if (!store || typeof store !== "object" || store.enabled !== true && store.enabled !== false)
+        throw new Error(`Raybase agent ${agent.name} skillStore.enabled must be boolean`);
+    if (!store.enabled)
+        return;
+    if (store.policy !== undefined && typeof store.policy !== "function")
+        throw new Error(`Raybase agent ${agent.name} skillStore.policy must be a function`);
+    boundedConfigLimit(agent.name, "maxSkills", store.limits?.maxSkills, raybaseAgentSkillStoreLimits.maxSkillsCap);
+    boundedConfigLimit(agent.name, "maxGuidanceBytes", store.limits?.maxGuidanceBytes, raybaseAgentSkillStoreLimits.maxGuidanceBytesCap);
+    const imports = store.agentAccess?.importSources ?? [];
+    if (!Array.isArray(imports) || imports.some((kind) => kind !== "direct-url" && kind !== "github"))
+        throw new Error(`Raybase agent ${agent.name} skillStore.agentAccess.importSources contains an unsupported source kind`);
+    for (const source of store.sources ?? []) {
+        if (!source || typeof source.url !== "string" || !source.url.trim())
+            throw new Error(`Raybase agent ${agent.name} skillStore source URL is required`);
+        validateOutboundHttpsUrl(source.url);
+        if (source.syncEveryMs !== undefined && source.syncEveryMs < 15 * 60 * 1000)
+            throw new Error(`Raybase agent ${agent.name} skillStore source syncEveryMs must be at least 15 minutes`);
+        if ((source.allowedArtifactOrigins?.length ?? 0) > 8)
+            throw new Error(`Raybase agent ${agent.name} skillStore source allows at most 8 artifact origins`);
+        for (const origin of source.allowedArtifactOrigins ?? [])
+            validateOutboundOrigin(origin);
+        if (source.authSecretName && !/^[A-Z][A-Z0-9_]*$/.test(source.authSecretName))
+            throw new Error(`Raybase agent ${agent.name} skillStore source authSecretName must be an uppercase environment binding name`);
+        for (const mapping of source.artifactAuth ?? []) {
+            validateOutboundOrigin(mapping.origin);
+            if (!source.allowedArtifactOrigins?.includes(mapping.origin))
+                throw new Error(`Raybase agent ${agent.name} skillStore artifact auth origin ${mapping.origin} must also be allowed`);
+            if (!/^[A-Z][A-Z0-9_]*$/.test(mapping.secretName))
+                throw new Error(`Raybase agent ${agent.name} skillStore artifact secretName must be an uppercase environment binding name`);
+        }
+    }
+}
+export function agentSkillStoreEnabled(agent) { return agent.skillStore?.enabled === true; }
+export async function listAgentSkills(control, agentName) {
+    return control.all(`SELECT * FROM ${q("_agent_skills")}${agentName ? ` WHERE "agentName" = ?` : ""} ORDER BY "agentName", "name"`, agentName ? [agentName] : []);
+}
+export async function findAgentSkill(control, agentName, name) {
+    return control.first(`SELECT * FROM ${q("_agent_skills")} WHERE "agentName" = ? AND "normalizedName" = ? LIMIT 1`, [agentName, normalizeSkillName(name)]);
+}
+export async function listAgentSkillFiles(control, skillId) {
+    return control.all(`SELECT "path", "kind", "encoding", "content", "bytes", "sha256" FROM ${q("_agent_skill_files")} WHERE "skillId" = ? ORDER BY "path"`, [skillId]);
+}
+export async function readAgentSkillFile(control, skillId, pathValue) {
+    const path = normalizeSkillPath(pathValue);
+    return control.first(`SELECT "path", "kind", "encoding", "content", "bytes", "sha256" FROM ${q("_agent_skill_files")} WHERE "skillId" = ? AND "normalizedPath" = ? LIMIT 1`, [skillId, normalizeSkillName(path)]);
+}
+export async function currentAgentSkillChapterId(control, conversationId) {
+    const last = await control.first(`SELECT "id" FROM ${q("_agent_chapters")} WHERE "conversationId" = ? ORDER BY "ordinal" DESC LIMIT 1`, [conversationId]);
+    return last?.id ?? "chapter:0";
+}
+export async function listLoadedAgentSkillNames(control, conversationId, chapterId) {
+    const effectiveChapterId = chapterId ?? await currentAgentSkillChapterId(control, conversationId);
+    const rows = await control.all(`SELECT "skillName" FROM ${q("_agent_skill_loads")} WHERE "conversationId" = ? AND "chapterId" = ? ORDER BY "skillName"`, [conversationId, effectiveChapterId]);
+    return rows.map((row) => row.skillName);
+}
+export async function loadAgentSkillForChapter(control, conversationId, skillName) {
+    const chapterId = await currentAgentSkillChapterId(control, conversationId);
+    const existing = await control.first(`SELECT "id" FROM ${q("_agent_skill_loads")} WHERE "conversationId" = ? AND "chapterId" = ? AND "skillName" = ? LIMIT 1`, [conversationId, chapterId, skillName]);
+    if (existing)
+        return { chapterId, alreadyLoaded: true };
+    await control.run(`INSERT OR IGNORE INTO ${q("_agent_skill_loads")} ("id","conversationId","chapterId","skillName","loadedAt") VALUES (?,?,?,?,?)`, [randomId("skill_load"), conversationId, chapterId, skillName, nowIso()]);
+    return { chapterId, alreadyLoaded: false };
+}
+export async function installAgentSkillPackage(control, input) {
+    const existing = await findAgentSkill(control, input.agentName, input.package.name);
+    const mode = input.mode ?? existing?.mode ?? (input.package.ephemeral ? "include" : "available");
+    assertSkillDurability(input.package.ephemeral, mode);
+    if (existing && !input.replace)
+        throw skillError("skill_conflict", `Skill ${input.package.name} already exists`, { source: existing.source, revision: existing.revision });
+    if (existing) {
+        if (input.expectedRevision !== existing.revision)
+            throw staleRevision(existing);
+        if (existing.source === "code")
+            throw skillError("ownership", `Code skill ${existing.name} can only change through code reconcile`);
+        const revision = existing.revision + 1;
+        const now = nowIso();
+        await mutateSkillWithCas(control, existing, input.reason ?? "replace", input.actorKind ?? input.ownerKind, input.actor ?? input.createdBy, [
+            { sql: `UPDATE ${q("_agent_skills")} SET "title"=?, "description"=?, "guidance"=?, "mode"=?, "ephemeral"=?, "contentDigest"=?, "lastImportedContentDigest"=?, "license"=?, "compatibility"=?, "metadataJson"=?, "enabled"=?, "revision"=?, "updatedAt"=? WHERE "id"=? AND "revision"=?`, params: [
+                    input.package.title ?? null, input.package.description, input.package.guidance, mode, input.package.ephemeral ? 1 : 0, input.package.contentDigest,
+                    input.source === "local" ? input.package.contentDigest : null, input.package.license ?? null, input.package.compatibility ?? null, input.package.metadataJson,
+                    input.enabled === undefined ? existing.enabled : input.enabled ? 1 : 0, revision, now, existing.id, existing.revision
+                ] },
+            ...replaceSkillFileStatements(existing.id, input.package.files, now)
+        ]);
+        return (await findAgentSkill(control, input.agentName, input.package.name));
+    }
+    const idValue = randomId("skill");
+    const now = nowIso();
+    await control.run(`INSERT INTO ${q("_agent_skills")} (
+    "id","agentName","normalizedName","name","title","description","guidance","mode","ephemeral","contentDigest","lastImportedContentDigest","license","compatibility","metadataJson","enabled","revision","source","ownerKind","ownerAgentName","createdBy","originKind","originUrl","originRef","originRefKind","originCommit","originRepo","originManifestPath","originSkillPath","originDigest","importedAt","sourceId","remoteSha256","syncedAt","syncStatus","syncError","createdAt","updatedAt"
+  ) VALUES (${Array.from({ length: 37 }, () => "?").join(",")})`, [
+        idValue, input.agentName, normalizeSkillName(input.package.name), input.package.name, input.package.title ?? null, input.package.description,
+        input.package.guidance, mode, input.package.ephemeral ? 1 : 0, input.package.contentDigest, input.source === "local" ? input.package.contentDigest : null,
+        input.package.license ?? null, input.package.compatibility ?? null, input.package.metadataJson, input.enabled === false ? 0 : 1, 1, input.source,
+        input.ownerKind, input.ownerAgentName ?? null, input.createdBy, input.originKind, input.originUrl ?? null, input.originRef ?? null,
+        input.originRefKind ?? null, input.originCommit ?? null, input.originRepo ?? null, input.originManifestPath ?? null, input.originSkillPath ?? null,
+        input.originDigest ?? null, input.source === "code" ? null : now, input.sourceId ?? null, input.remoteSha256 ?? null,
+        input.source === "managed" ? now : null, input.source === "managed" ? "ok" : null, null, now, now
+    ]);
+    await replaceSkillFiles(control, idValue, input.package.files);
+    return (await findAgentSkill(control, input.agentName, input.package.name));
+}
+export function resolveAgentSkillCreationMode(mode, ephemeral) {
+    const resolved = mode === "include" ? "include" : mode === "available" ? "available" : ephemeral ? "include" : "available";
+    assertSkillDurability(ephemeral, resolved);
+    return resolved;
+}
+export async function editAgentSkill(control, input) {
+    const row = await requiredSkill(control, input.agentName, input.name);
+    assertEditable(row, input.actorKind, input.agentName);
+    assertRevision(row, input.expectedRevision);
+    let guidance = row.guidance;
+    if (input.replaceGuidance !== undefined)
+        guidance = input.replaceGuidance;
+    else if (input.findText !== undefined)
+        guidance = replaceExactlyOnce(guidance, input.findText, input.replaceWith ?? "");
+    assertGuidanceBytes(guidance, input.maxGuidanceBytes ?? raybaseAgentSkillStoreLimits.maxGuidanceBytesCap);
+    const description = input.description ?? row.description;
+    if (!description.trim())
+        throw skillError("validation", "Skill description cannot be empty");
+    const mode = input.mode ?? row.mode;
+    const ephemeral = input.ephemeral === undefined ? row.ephemeral === 1 : input.ephemeral;
+    assertSkillDurability(ephemeral, mode);
+    const contentDigest = await computeEditedDigest(row, { title: input.title === undefined ? row.title : input.title, description, guidance, mode, ephemeral });
+    await mutateSkillWithCas(control, row, "edit", input.actorKind, input.actor, [{ sql: `UPDATE ${q("_agent_skills")} SET "title"=?,"description"=?,"guidance"=?,"mode"=?,"ephemeral"=?,"contentDigest"=?,"revision"=?,"updatedAt"=? WHERE "id"=? AND "revision"=?`, params: [
+                input.title === undefined ? row.title : input.title, description, guidance, mode, ephemeral ? 1 : 0, contentDigest, row.revision + 1, nowIso(), row.id, row.revision
+            ] }]);
+    return (await findAgentSkill(control, input.agentName, input.name));
+}
+export async function setAgentSkillEnabled(control, input) {
+    const row = await requiredSkill(control, input.agentName, input.name);
+    assertRevision(row, input.expectedRevision);
+    await mutateSkillWithCas(control, row, input.enabled ? "enable" : "disable", input.actorKind, input.actor, [{ sql: `UPDATE ${q("_agent_skills")} SET "enabled"=?,"revision"=?,"updatedAt"=? WHERE "id"=? AND "revision"=?`, params: [input.enabled ? 1 : 0, row.revision + 1, nowIso(), row.id, row.revision] }]);
+    return (await findAgentSkill(control, input.agentName, input.name));
+}
+export async function deleteAgentSkill(control, input) {
+    const row = await requiredSkill(control, input.agentName, input.name);
+    assertEditable(row, input.actorKind, input.agentName);
+    assertRevision(row, input.expectedRevision);
+    await mutateSkillWithCas(control, row, "delete", input.actorKind, input.actor, [
+        { sql: `DELETE FROM ${q("_agent_skill_files")} WHERE "skillId"=?`, params: [row.id] },
+        { sql: `DELETE FROM ${q("_agent_skills")} WHERE "id"=? AND "revision"=?`, params: [row.id, row.revision] }
+    ]);
+}
+/**
+ * Delete the source before its dependents, with a transaction-local guard
+ * that aborts (rather than merely no-ops) when the source CAS has lost.
+ */
+export async function removeManagedAgentSkillSource(control, input) {
+    const source = await control.first(`SELECT * FROM ${q("_agent_skill_sources")} WHERE "id"=?${input.agentName ? ' AND "agentName"=?' : ""} AND "registeredBy"='operator'`, input.agentName ? [input.sourceId, input.agentName] : [input.sourceId]);
+    if (!source)
+        throw new Error("Operator-owned managed source not found");
+    if (source.revision !== input.expectedRevision)
+        throw new Error("Managed source revision changed; refresh and retry");
+    if (!control.runTransaction)
+        throw new Error("Managed source removal requires transaction support");
+    const guardId = randomId("skill_source_cas_guard");
+    const now = nowIso();
+    const statements = [
+        // `id()` is not necessarily a NOT NULL SQLite primary key.  Put the
+        // conditional value in a known-required column so a lost CAS aborts this
+        // transaction instead of merely producing a zero-row guard marker.
+        { sql: `INSERT INTO ${q("_agent_skill_revisions")} ("id","skillId","revision","title","description","guidance","mode","ephemeral","enabled","contentDigest","reason","actorKind","actor","createdAt") SELECT ?,?,?,?,CASE WHEN EXISTS (SELECT 1 FROM ${q("_agent_skill_sources")} WHERE "id"=? AND "revision"=? AND "registeredBy"='operator') THEN ? ELSE NULL END,?,?,?,?,?,?,?,?,?`, params: [guardId, input.sourceId, 0, null, input.sourceId, input.expectedRevision, "", "", "available", 0, 0, "", "source_cas_guard", "system", null, now] },
+        { sql: `DELETE FROM ${q("_agent_skill_sources")} WHERE "id"=? AND "revision"=? AND "registeredBy"='operator'`, params: [input.sourceId, input.expectedRevision] }
+    ];
+    if (input.deleteSkills) {
+        statements.push({ sql: `DELETE FROM ${q("_agent_skill_files")} WHERE "skillId" IN (SELECT "id" FROM ${q("_agent_skills")} WHERE "sourceId"=?)`, params: [input.sourceId] }, { sql: `DELETE FROM ${q("_agent_skills")} WHERE "sourceId"=?`, params: [input.sourceId] });
+    }
+    else {
+        statements.push({ sql: `UPDATE ${q("_agent_skills")} SET "enabled"=0,"syncStatus"='orphaned',"sourceId"=NULL,"revision"="revision"+1,"updatedAt"=? WHERE "sourceId"=?`, params: [now, input.sourceId] });
+    }
+    statements.push({ sql: `DELETE FROM ${q("_agent_skill_revisions")} WHERE "id"=?`, params: [guardId] });
+    try {
+        await control.runTransaction(statements);
+    }
+    catch (error) {
+        const current = await control.first(`SELECT * FROM ${q("_agent_skill_sources")} WHERE "id"=? AND "registeredBy"='operator'`, [input.sourceId]);
+        if (!current || current.revision !== input.expectedRevision)
+            throw new Error("Managed source revision changed; refresh and retry");
+        throw error;
+    }
+}
+export async function createAgentSkillUpload(control, input) {
+    if (input.bytes.byteLength > raybaseAgentSkillStoreLimits.uploadBytes)
+        throw skillError("upload_too_large", "Upload exceeds the 10 MiB limit");
+    const uploadId = randomId("skill_upload");
+    const sha256 = await sha256Hex(input.bytes);
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + raybaseAgentSkillStoreLimits.uploadTtlMs).toISOString();
+    await control.run(`INSERT INTO ${q("_agent_skill_uploads")} ("id","agentName","filename","contentBase64","bytes","sha256","createdByUserId","createdAt","expiresAt") VALUES (?,?,?,?,?,?,?,?,?)`, [
+        uploadId, input.agentName, input.filename, bytesToBase64(input.bytes), input.bytes.byteLength, sha256, input.createdByUserId ?? null, now.toISOString(), expiresAt
+    ]);
+    return { uploadId, sha256, bytes: input.bytes.byteLength, filename: input.filename, expiresAt };
+}
+export async function getAgentSkillUpload(control, agentName, uploadId) {
+    return control.first(`SELECT "id","filename","contentBase64","bytes","sha256","expiresAt" FROM ${q("_agent_skill_uploads")} WHERE "id"=? AND "agentName"=? LIMIT 1`, [uploadId, agentName]);
+}
+export async function sweepExpiredAgentSkillUploads(control, at = nowIso()) { await control.run(`DELETE FROM ${q("_agent_skill_uploads")} WHERE "expiresAt" <= ?`, [at]); }
+export async function databaseAgentSkills(control, agentName) {
+    const rows = (await listAgentSkills(control, agentName)).filter((row) => row.enabled === 1);
+    const output = [];
+    for (const row of rows) {
+        const files = await listAgentSkillFiles(control, row.id);
+        output.push({
+            skill: { name: row.name, namespace: row.name, ...(row.title ? { title: row.title } : {}), description: row.description, guidance: row.guidance, ...(row.ephemeral === 1 ? { ephemeral: true } : {}), actions: [], files: files.map((file) => ({ path: file.path, content: file.content })) },
+            result: row.mode,
+            row
+        });
+    }
+    return output;
+}
+export async function reconcileAgentSkillStore(control, agent) {
+    if (!agentSkillStoreEnabled(agent))
+        return { managedSourceSyncNeeded: false };
+    let managedSourceSyncNeeded = false;
+    const registrations = agentSkillRegistrations(agent.skills, agent.name);
+    const declaredNames = new Set(registrations.map(({ skill }) => normalizeSkillName(skill.name)));
+    for (const { skill, mode: registrationMode } of registrations) {
+        const mode = registrationMode === "include" || registrationMode === "available"
+            ? registrationMode
+            : skill.ephemeral ? "include" : "available";
+        const contentDigest = await sha256Hex(stableJson({
+            name: skill.name,
+            title: skill.title ?? null,
+            description: skill.description ?? "",
+            guidance: skill.guidance ?? "",
+            mode,
+            ephemeral: skill.ephemeral === true,
+            maxChars: skill.maxChars ?? null,
+            onOverflow: skill.onOverflow ?? "truncate",
+            files: await Promise.all((skill.files ?? []).map(async (file) => ({ path: file.path, sha256: await sha256Hex(file.content) }))),
+            actions: skill.actions.map((action) => action.name).sort(),
+            limits: skill.limits ?? null
+        }));
+        const existing = await findAgentSkill(control, agent.name, skill.name);
+        if (existing?.source !== undefined && existing.source !== "code") {
+            console.warn(`Raybase agent ${agent.name} code skill ${skill.name} collides with a ${existing.source} database skill; the code registration wins and the database row is ignored`);
+            continue;
+        }
+        if (existing?.contentDigest === contentDigest && existing.syncStatus !== "orphaned")
+            continue;
+        const pkg = {
+            name: skill.name,
+            ...(skill.title ? { title: skill.title } : {}),
+            description: skill.description ?? "",
+            guidance: skill.guidance ?? "",
+            ephemeral: skill.ephemeral === true,
+            metadataJson: stableJson({ actions: skill.actions.map((action) => action.name), limits: skill.limits ?? null }),
+            files: await Promise.all((skill.files ?? []).map(async (file) => {
+                const bytes = new TextEncoder().encode(file.content);
+                return { path: file.path, kind: codeSkillFileKind(file.path), encoding: "utf8", content: file.content, bytes: bytes.byteLength, sha256: await sha256Hex(bytes) };
+            })),
+            contentDigest
+        };
+        if (existing) {
+            await captureSkillRevision(control, existing, "reconcile", "code", "defineAgent");
+            await control.run(`UPDATE ${q("_agent_skills")} SET "title"=?,"description"=?,"guidance"=?,"mode"=?,"ephemeral"=?,"contentDigest"=?,"metadataJson"=?,"syncStatus"=NULL,"syncError"=NULL,"revision"=?,"updatedAt"=? WHERE "id"=?`, [pkg.title ?? null, pkg.description, pkg.guidance, mode, pkg.ephemeral ? 1 : 0, pkg.contentDigest, pkg.metadataJson, existing.revision + 1, nowIso(), existing.id]);
+            await replaceSkillFiles(control, existing.id, pkg.files);
+        }
+        else {
+            await installAgentSkillPackage(control, { agentName: agent.name, package: pkg, source: "code", ownerKind: "code", createdBy: "defineAgent", originKind: "code", mode });
+        }
+    }
+    for (const row of await listAgentSkills(control, agent.name)) {
+        if (row.source === "code" && !declaredNames.has(row.normalizedName) && (row.enabled !== 0 || row.syncStatus !== "orphaned")) {
+            await captureSkillRevision(control, row, "reconcile", "code", "defineAgent");
+            await control.run(`UPDATE ${q("_agent_skills")} SET "enabled"=0,"syncStatus"='orphaned',"revision"=?,"updatedAt"=? WHERE "id"=?`, [row.revision + 1, nowIso(), row.id]);
+        }
+    }
+    const declaredSourceUrls = new Set();
+    for (const definition of agent.skillStore?.sources ?? []) {
+        declaredSourceUrls.add(definition.url);
+        const existing = await control.first(`SELECT * FROM ${q("_agent_skill_sources")} WHERE "agentName"=? AND "url"=? LIMIT 1`, [agent.name, definition.url]);
+        const syncEveryMs = definition.syncEveryMs ?? 6 * 60 * 60 * 1000;
+        const authSecretName = definition.authSecretName ?? null;
+        const allowedArtifactOriginsJson = stableJson(definition.allowedArtifactOrigins ?? []);
+        const artifactAuthJson = stableJson(definition.artifactAuth ?? []);
+        const selectionMode = definition.selection === "all" || definition.selection === undefined ? "all" : "named";
+        const selectedNamesJson = stableJson(Array.isArray(definition.selection) ? definition.selection : []);
+        if (existing) {
+            if (existing.registeredBy !== "code") {
+                console.warn(`Raybase agent ${agent.name} code-defined skill source ${definition.url} collides with an operator-owned source; the operator source remains authoritative`);
+                continue;
+            }
+            if (existing.enabled === 1
+                && existing.syncEveryMs === syncEveryMs
+                && existing.authSecretName === authSecretName
+                && existing.allowedArtifactOriginsJson === allowedArtifactOriginsJson
+                && existing.artifactAuthJson === artifactAuthJson
+                && existing.selectionMode === selectionMode
+                && existing.selectedNamesJson === selectedNamesJson) {
+                if (!existing.lastSyncAt)
+                    managedSourceSyncNeeded = true;
+                continue;
+            }
+            await control.run(`UPDATE ${q("_agent_skill_sources")} SET "enabled"=1,"revision"="revision"+1,"syncEveryMs"=?,"authSecretName"=?,"allowedArtifactOriginsJson"=?,"artifactAuthJson"=?,"selectionMode"=?,"selectedNamesJson"=?,"updatedAt"=? WHERE "id"=? AND "revision"=? AND "registeredBy"='code'`, [syncEveryMs, authSecretName, allowedArtifactOriginsJson, artifactAuthJson, selectionMode, selectedNamesJson, nowIso(), existing.id, existing.revision]);
+            managedSourceSyncNeeded = true;
+            continue;
+        }
+        const now = nowIso();
+        await control.run(`INSERT INTO ${q("_agent_skill_sources")} ("id","agentName","sourceType","url","registeredBy","enabled","revision","syncEveryMs","authSecretName","allowedArtifactOriginsJson","artifactAuthJson","selectionMode","selectedNamesJson","createdAt","updatedAt") VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, [randomId("skill_source"), agent.name, "http-index", definition.url, "code", 1, 1, syncEveryMs, authSecretName, allowedArtifactOriginsJson, artifactAuthJson, selectionMode, selectedNamesJson, now, now]);
+        managedSourceSyncNeeded = true;
+    }
+    for (const source of await control.all(`SELECT * FROM ${q("_agent_skill_sources")} WHERE "agentName"=? AND "registeredBy"='code'`, [agent.name])) {
+        if (declaredSourceUrls.has(source.url) || source.enabled === 0)
+            continue;
+        const now = nowIso();
+        if (!control.runTransaction)
+            throw new Error("Code-defined Agent Skill source removal requires transaction support");
+        await control.runTransaction([
+            { sql: `UPDATE ${q("_agent_skill_sources")} SET "enabled"=0,"revision"="revision"+1,"updatedAt"=? WHERE "id"=? AND "revision"=? AND "registeredBy"='code'`, params: [now, source.id, source.revision] },
+            { sql: `UPDATE ${q("_agent_skills")} SET "enabled"=0,"syncStatus"='orphaned',"revision"="revision"+1,"updatedAt"=? WHERE "sourceId"=? AND "source"='managed' AND EXISTS (SELECT 1 FROM ${q("_agent_skill_sources")} WHERE "id"=? AND "revision"=? AND "enabled"=0 AND "registeredBy"='code')`, params: [now, source.id, source.id, source.revision + 1] }
+        ]);
+    }
+    return { managedSourceSyncNeeded };
+}
+export function agentSkillStoreRuntimeTools(input) {
+    if (!agentSkillStoreEnabled(input.agent))
+        return [];
+    const signedIn = input.principal.kind !== "public";
+    const access = input.agent.skillStore?.agentAccess ?? {};
+    const excluded = new Set((input.resolvedTurn?.skills ?? []).filter(({ verdict }) => verdict === "excluded").map(({ skill }) => normalizeSkillName(skill.name)));
+    const visibleRows = async () => (await listAgentSkills(input.control, input.agent.name)).filter((row) => !excluded.has(row.normalizedName));
+    const visibleSkill = async (name) => {
+        const row = await requiredSkill(input.control, input.agent.name, name);
+        if (excluded.has(row.normalizedName))
+            throw skillError("not_found", `Skill ${name} was not found`);
+        return row;
+    };
+    const tools = [
+        tool("skill_list", "List installed skills", "List installed database-backed skills and their revisions.", {}, async () => (await visibleRows()).map(publicSkill)),
+        tool("skill_read", "Read skill metadata", "Read metadata, digest, and the supporting-file manifest for one installed skill. Use load_agent_skill for guidance and read_skill for files.", { name: { type: "string" } }, async (args) => {
+            const row = await visibleSkill(argString(args, "name"));
+            return { ...publicSkill(row), files: (await listAgentSkillFiles(input.control, row.id)).map(({ path, kind, bytes, sha256 }) => ({ path, kind, bytes, sha256 })), guidanceAccess: "Use load_agent_skill to load guidance and read_skill to read supporting files." };
+        })
+    ];
+    if (!signedIn)
+        return tools;
+    if (access.create)
+        tools.push(tool("skill_write", "Write skill", "Create an agent-owned local skill.", { name: { type: "string" }, description: { type: "string" }, guidance: { type: "string" }, title: { type: "string" }, mode: { type: "string", enum: ["include", "available"] }, ephemeral: { type: "boolean" } }, async (args) => {
+            const record = argRecord(args);
+            const name = validateOpenAgentSkillName(record.name);
+            const guidance = argString(args, "guidance");
+            const description = argString(args, "description");
+            const maxSkills = input.agent.skillStore?.limits?.maxSkills ?? raybaseAgentSkillStoreLimits.maxSkills;
+            const maxGuidanceBytes = input.agent.skillStore?.limits?.maxGuidanceBytes ?? raybaseAgentSkillStoreLimits.maxGuidanceBytes;
+            assertGuidanceBytes(guidance, maxGuidanceBytes);
+            if ((await listAgentSkills(input.control, input.agent.name)).length >= maxSkills)
+                throw skillError("skill_limit", `Agent skill limit of ${maxSkills} would be exceeded`);
+            const ephemeral = record.ephemeral === true;
+            const pkg = await inlinePackage(name, typeof record.title === "string" ? record.title : undefined, description, guidance, ephemeral);
+            const actor = principalActor(input.principal);
+            const mode = resolveAgentSkillCreationMode(record.mode, ephemeral);
+            const row = await installAgentSkillPackage(input.control, { agentName: input.agent.name, package: pkg, source: "local", ownerKind: "agent", ownerAgentName: input.agent.name, createdBy: actor, originKind: "inline", mode });
+            await auditSkill(input, "agent.skills.apply", row, { originKind: "inline" });
+            return publicSkill(row);
+        }, true));
+    if (access.edit)
+        tools.push(tool("skill_edit", "Edit skill", "CAS-edit one owned local skill.", { name: { type: "string" }, expectedRevision: { type: "integer" }, replaceGuidance: { type: "string" }, findText: { type: "string" }, replaceWith: { type: "string" }, title: { type: "string" }, description: { type: "string" }, mode: { type: "string", enum: ["include", "available"] }, ephemeral: { type: "boolean" } }, async (args) => {
+            const record = argRecord(args);
+            const row = await editAgentSkill(input.control, { agentName: input.agent.name, name: argString(args, "name"), expectedRevision: argRevision(args), actorKind: "agent", actor: principalActor(input.principal), title: typeof record.title === "string" ? record.title : undefined, description: typeof record.description === "string" ? record.description : undefined, mode: record.mode === "include" ? "include" : record.mode === "available" ? "available" : undefined, ephemeral: typeof record.ephemeral === "boolean" ? record.ephemeral : undefined, replaceGuidance: typeof record.replaceGuidance === "string" ? record.replaceGuidance : undefined, findText: typeof record.findText === "string" ? record.findText : undefined, replaceWith: typeof record.replaceWith === "string" ? record.replaceWith : undefined, maxGuidanceBytes: input.agent.skillStore?.limits?.maxGuidanceBytes ?? raybaseAgentSkillStoreLimits.maxGuidanceBytes });
+            await auditSkill(input, "agent.skills.edit", row, {});
+            return publicSkill(row);
+        }, true));
+    if (access.delete)
+        tools.push(tool("skill_delete", "Delete skill", "CAS-delete one owned local skill.", { name: { type: "string" }, expectedRevision: { type: "integer" } }, async (args) => { const name = argString(args, "name"); const revision = argRevision(args); const row = await requiredSkill(input.control, input.agent.name, name); await deleteAgentSkill(input.control, { agentName: input.agent.name, name, expectedRevision: revision, actorKind: "agent", actor: principalActor(input.principal) }); await auditSkill(input, "agent.skills.delete", row, {}); return { ok: true, name }; }, true));
+    if (access.setEnabled)
+        tools.push(tool("skill_set_enabled", "Set skill enabled", "CAS-toggle one installed skill from any source.", { name: { type: "string" }, enabled: { type: "boolean" }, expectedRevision: { type: "integer" } }, async (args) => { const record = argRecord(args); const row = await setAgentSkillEnabled(input.control, { agentName: input.agent.name, name: argString(args, "name"), enabled: record.enabled === true, expectedRevision: argRevision(args), actorKind: "agent", actor: principalActor(input.principal) }); await auditSkill(input, row.enabled ? "agent.skills.enable" : "agent.skills.disable", row, {}); return publicSkill(row); }, true));
+    return tools;
+}
+function replaceSkillFileStatements(skillId, files, createdAt = nowIso()) {
+    const statements = [{ sql: `DELETE FROM ${q("_agent_skill_files")} WHERE "skillId"=?`, params: [skillId] }];
+    for (const file of files)
+        statements.push({ sql: `INSERT INTO ${q("_agent_skill_files")} ("id","skillId","path","normalizedPath","kind","encoding","content","bytes","sha256","createdAt") VALUES (?,?,?,?,?,?,?,?,?,?)`, params: [randomId("skill_file"), skillId, file.path, normalizeSkillName(file.path), file.kind, file.encoding, file.content, file.bytes, file.sha256, createdAt] });
+    return statements;
+}
+async function replaceSkillFiles(control, skillId, files) {
+    const statements = replaceSkillFileStatements(skillId, files);
+    if (control.runTransaction)
+        await control.runTransaction(statements);
+    else
+        for (const statement of statements)
+            await control.run(statement.sql, statement.params);
+}
+async function captureSkillRevision(control, row, reason, actorKind, actor) {
+    await control.run(`INSERT INTO ${q("_agent_skill_revisions")} ("id","skillId","revision","title","description","guidance","mode","ephemeral","enabled","contentDigest","reason","actorKind","actor","createdAt") VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, [randomId("skill_rev"), row.id, row.revision, row.title, row.description, row.guidance, row.mode, row.ephemeral, row.enabled, row.contentDigest, reason, actorKind, actor, nowIso()]);
+    await control.run(`DELETE FROM ${q("_agent_skill_revisions")} WHERE "skillId"=? AND "id" NOT IN (SELECT "id" FROM ${q("_agent_skill_revisions")} WHERE "skillId"=? ORDER BY "createdAt" DESC LIMIT ?)`, [row.id, row.id, raybaseAgentSkillStoreLimits.revisionsPerSkill]);
+}
+/** A conditional snapshot is the CAS success marker and captures only the state actually replaced. */
+async function mutateSkillWithCas(control, row, reason, actorKind, actor, mutation) {
+    if (!control.runTransaction)
+        throw new Error("Agent Skill mutation requires transaction support");
+    const revisionId = randomId("skill_rev");
+    const guardId = randomId("skill_cas_guard");
+    try {
+        await control.runTransaction([
+            { sql: `DELETE FROM ${q("_agent_skill_revisions")} WHERE "skillId"=? AND "id" NOT IN (SELECT "id" FROM ${q("_agent_skill_revisions")} WHERE "skillId"=? ORDER BY "createdAt" DESC LIMIT ?)`, params: [row.id, row.id, raybaseAgentSkillStoreLimits.revisionsPerSkill - 1] },
+            // Use a scalar EXISTS rather than SELECTing from the row: the latter
+            // silently writes zero rows when stale.  `description` is required, so
+            // the NULL branch forces SQLite to roll back the whole transaction.
+            { sql: `INSERT INTO ${q("_agent_skill_revisions")} ("id","skillId","revision","title","description","guidance","mode","ephemeral","enabled","contentDigest","reason","actorKind","actor","createdAt") SELECT ?,?,?,?,CASE WHEN EXISTS (SELECT 1 FROM ${q("_agent_skills")} WHERE "id"=? AND "revision"=?) THEN ? ELSE NULL END,?,?,?,?,?,?,?,?,?`, params: [guardId, row.id, 0, null, row.id, row.revision, "", "", "available", 0, 0, "", "cas_guard", "system", null, nowIso()] },
+            { sql: `INSERT INTO ${q("_agent_skill_revisions")} ("id","skillId","revision","title","description","guidance","mode","ephemeral","enabled","contentDigest","reason","actorKind","actor","createdAt") SELECT ?,"id","revision","title","description","guidance","mode","ephemeral","enabled","contentDigest",?,?,?,? FROM ${q("_agent_skills")} WHERE "id"=? AND "revision"=?`, params: [revisionId, reason, actorKind, actor, nowIso(), row.id, row.revision] },
+            ...mutation,
+            { sql: `DELETE FROM ${q("_agent_skill_revisions")} WHERE "id"=?`, params: [guardId] }
+        ]);
+    }
+    catch (error) {
+        const current = await findAgentSkill(control, row.agentName, row.name);
+        if (!current || current.revision !== row.revision)
+            throw staleRevision(current ?? row);
+        throw error;
+    }
+    const marker = await control.first(`SELECT "id" FROM ${q("_agent_skill_revisions")} WHERE "id"=?`, [revisionId]);
+    if (!marker) {
+        const current = await findAgentSkill(control, row.agentName, row.name);
+        throw staleRevision(current ?? row);
+    }
+}
+function assertRevision(row, expected) { if (!Number.isInteger(expected) || expected !== row.revision)
+    throw staleRevision(row); }
+function staleRevision(row) { return skillError("stale_revision", `Skill ${row.name} changed since it was read`, { currentRevision: row.revision, updatedAt: row.updatedAt }); }
+function assertEditable(row, actorKind, agentName) { if (row.source !== "local")
+    throw skillError("ownership", `${row.source} skill ${row.name} cannot be edited directly`); if (actorKind === "agent")
+    assertAgentOwned(row, agentName); }
+function assertAgentOwned(row, agentName) { if (row.ownerKind !== "agent" || row.ownerAgentName !== agentName || row.source !== "local")
+    throw skillError("ownership", `Skill ${row.name} is not owned by agent ${agentName}`); }
+async function requiredSkill(control, agentName, name) { const row = await findAgentSkill(control, agentName, name); if (!row)
+    throw skillError("not_found", `Skill ${name} was not found`); return row; }
+function replaceExactlyOnce(body, find, replacement) { const first = body.indexOf(find); if (first < 0)
+    throw skillError("not_found", "Skill edit text was not found"); if (body.indexOf(find, first + Math.max(1, find.length)) >= 0)
+    throw skillError("ambiguous_edit", "Skill edit text occurs more than once"); return body.slice(0, first) + replacement + body.slice(first + find.length); }
+async function computeEditedDigest(row, value) { return sha256Hex(stableJson({ name: row.name, ...value, metadataJson: row.metadataJson })); }
+function normalizeSkillName(value) { return value.normalize("NFC").toLocaleLowerCase("en-US"); }
+function boundedConfigLimit(agentName, field, value, cap) { if (value !== undefined && (!Number.isInteger(value) || value < 1 || value > cap))
+    throw new Error(`Raybase agent ${agentName} skillStore.limits.${field} must be an integer between 1 and ${cap}`); }
+function assertGuidanceBytes(guidance, maxBytes) { const bytes = new TextEncoder().encode(guidance).byteLength; if (bytes > maxBytes)
+    throw skillError("guidance_too_large", `Skill guidance exceeds ${maxBytes} bytes`, { bytes, maxBytes }); }
+function assertSkillDurability(ephemeral, mode) { if (ephemeral && mode === "available")
+    throw skillError("invalid_durability", "Ephemeral Agent Skills must use include mode"); }
+function codeSkillFileKind(path) { const head = path.split("/", 1)[0]; return head === "references" ? "reference" : head === "assets" ? "asset" : head === "scripts" ? "script" : "other"; }
+function skillError(code, message, details) { return new RaybaseActionError(message, { code, retryable: code === "stale_revision" || code === "ambiguous_edit" || code === "not_found", ...details }); }
+function publicSkill(row) { return { name: row.name, title: row.title, description: row.description, source: row.source, mode: row.mode, ephemeral: row.ephemeral === 1, enabled: row.enabled === 1, revision: row.revision, contentDigest: row.contentDigest, ownerKind: row.ownerKind, syncStatus: row.syncStatus, updatedAt: row.updatedAt }; }
+function argRecord(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : {}; }
+function argString(value, key) { const item = argRecord(value)[key]; if (typeof item !== "string" || !item.trim())
+    throw skillError("validation", `${key} is required`); return item.trim(); }
+function argRevision(value) { const item = argRecord(value).expectedRevision; if (!Number.isInteger(item))
+    throw skillError("validation", "expectedRevision must be an integer"); return item; }
+function principalActor(principal) { return principal.kind === "public" ? `public:${principal.id}` : principal.user.id; }
+function tool(name, displayName, description, properties, run, dataChange = false) { return { name, displayName, description, parameters: { type: "object", properties, additionalProperties: false }, dataChange: dataChange ? { actionName: name, effects: ["agent-skills"] } : null, run }; }
+async function inlinePackage(name, title, description, guidance, ephemeral = false) { const metadataJson = "{}"; const contentDigest = await sha256Hex(stableJson({ name, title, description, guidance, ephemeral, metadataJson })); return { name, ...(title ? { title } : {}), description, guidance, ephemeral, metadataJson, files: [], contentDigest }; }
+async function auditSkill(input, action, row, metadata) { await recordAudit(input.control, { actor: input.principal, action, target: { type: "_agent_skills", id: row.id }, metadata: { agentName: input.agent.name, name: row.name, revision: row.revision, contentDigest: row.contentDigest, conversationId: input.conversationId, runId: input.runId, ...metadata } }); }
+function bytesToBase64(bytes) { let binary = ""; for (let offset = 0; offset < bytes.length; offset += 0x8000)
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000)); return btoa(binary); }
+//# sourceMappingURL=agent-skill-store.js.map