neotoma 0.22.2 → 0.23.0

package/dist/server.js

@@ -23,6 +23,7 @@ import { prepareEntitySnapshotWithEmbedding, upsertEntitySnapshotWithEmbedding,
 import { getLatestFromRegistry, isUpdateAvailable, formatUpgradeCommand } from "./version_check.js";
 import { buildSessionInfo, resolveConfiguredSessionOrigin, } from "./services/session_info.js";
 import { getActiveStandingRulesResult } from "./services/standing_rules.js";
+import { getInstanceSkillsResult, renderInstanceSkillsSection, } from "./services/skills/instance_skills.js";
 import { AttributionPolicyError } from "./services/attribution_policy.js";
 import { OverridePolicyViolationError } from "./services/override_validation.js";
 import { CursorError } from "./services/entity_cursor.js";
@@ -207,8 +208,13 @@ export class NeotomaServer {
      * separate discovery round-trip.
      *
      * Returns an empty array when the `skills/` directory is absent (e.g. in
-     * development checkouts that have not yet staged skill assets, or in test
-     * environments with stripped package layouts).
+     * development checkouts that have not yet staged skill assets, in test
+     * environments with stripped package layouts, or on a hosted instance whose
+     * skills live in the graph rather than on disk).
+     *
+     * This is only one of two skill sources. Graph-stored `skill` entities are
+     * read separately by `getInstanceSkills()` and unioned with this list in
+     * {@link buildAuthenticatedInitializeResponse} (issue #2046).
      */
     getAvailableSkills() {
         const roots = [config.projectRoot, resolveNeotomaPackageRoot()];
@@ -544,7 +550,9 @@ export class NeotomaServer {
         catch (err) {
             logger.warn(`[instance_policy] instructions render skipped: ${err.message}`);
         }
-        const instructions = composeClientInstructions(baseInstructions, policySection);
+        // Deferred until the instance-skills section is rendered below, so both
+        // appended sections compose through the same helper rather than one going
+        // through it and the other being concatenated on afterwards.
         // Load standing rules for the authenticated user and inject them so agents
         // apply them from the first turn of the session (issue #184).
         let standingRules = [];
@@ -558,7 +566,47 @@ export class NeotomaServer {
             standingRules = result.rules;
             standingRulesLookupFailed = result.lookup_failed;
         }
-        const availableSkills = this.getAvailableSkills();
+        // Skills reach agents two ways: mirrored to a local skills directory, or
+        // stored in the graph as `skill` rows. A hosted instance has only the
+        // latter, so the filesystem scan alone leaves MCP-only clients unable to
+        // discover any skill the instance holds (issue #2046). Union both sources
+        // so either deployment shape surfaces its skills.
+        //
+        // Gated by `config.mcpInstanceSkillHints`, which defaults ON: an operator
+        // who wants the section gone sets NEOTOMA_MCP_INSTANCE_SKILL_HINTS=0, and
+        // the lookup is then skipped entirely rather than performed and discarded,
+        // leaving the instructions byte-identical to what they were before this
+        // feature existed.
+        //
+        // As with standing rules, an empty list is ambiguous: it means either "no
+        // skill rows" or "the read failed". Carry the distinction so a broken read
+        // is never presented to an agent as a confident "this instance has none".
+        let instanceSkills = [];
+        let instanceSkillsLookupFailed = false;
+        if (this.authenticatedUserId && config.mcpInstanceSkillHints) {
+            const result = await getInstanceSkillsResult(this.authenticatedUserId);
+            instanceSkills = result.skills;
+            instanceSkillsLookupFailed = result.lookup_failed;
+        }
+        const filesystemSkills = this.getAvailableSkills();
+        const availableSkills = Array.from(new Set([...filesystemSkills, ...instanceSkills.map((s) => s.name)])).sort();
+        // An instance with no skill rows is a complete no-op: the renderer returns
+        // null and the instructions block is left exactly as it was.
+        //
+        // A FAILED read is not a no-op, though. The agent reads prose, not
+        // serverInfo, so the unavailable state is stated here too — otherwise the
+        // only signal lives in a field the consumer of the instruction block never
+        // looks at, and the failure stays effectively silent where it matters.
+        const skillsSection = instanceSkillsLookupFailed
+            ? "[INSTANCE SKILLS]\nThis instance's graph-stored skills could not be read for this session, so " +
+                "the list below (if any) is incomplete. Do NOT tell the user this instance has no skills. " +
+                "Treat its skills as unknown, retry on a later connection, and check the server logs for " +
+                "the `[instance_skills]` warning if this persists."
+            : renderInstanceSkillsSection(instanceSkills, config.mcpCompactInstructions);
+        // Nested rather than variadic: `composeClientInstructions` takes one
+        // section, and each call no-ops on an empty one, so an instance with no
+        // policy and no skill rows gets byte-identical instructions to before.
+        const instructions = composeClientInstructions(composeClientInstructions(baseInstructions, policySection), skillsSection);
         return {
             protocolVersion: "2025-11-25",
             capabilities: {
@@ -582,6 +630,12 @@ export class NeotomaServer {
                         }
                         : {}),
                     available_skills: availableSkills,
+                    ...(instanceSkillsLookupFailed
+                        ? {
+                            skills_unavailable: true,
+                            skills_note: "Instance-stored skills could not be read for this session. An empty or filesystem-only available_skills here does NOT mean this instance has no skills — treat the instance's skills as unknown rather than absent, and say so rather than telling the user none exist.",
+                        }
+                        : {}),
                 },
             },
             instructions,
@@ -4480,15 +4534,67 @@ export class NeotomaServer {
                         `Use a unique idempotency_key for each distinct write.`);
                     throw mismatchErr;
                 }
-                const { data: existingObservations, error: obsError } = await db
+                // Combined stores with interpretation.source_ref=unstructured write
+                // observations against the unstructured source, while the structured
+                // JSON source still owns the idempotency key. Exact replay must look
+                // up observations on the interpretation source when one was selected,
+                // then resolve the entities this request stored — sibling provenance
+                // rows (e.g. audio_asset) and other interpretations of the same bytes
+                // must not displace them.
+                const observationSourceId = options.interpretationSourceId ??
+                    (typeof interpretation?.source_id === "string" ? interpretation.source_id : undefined) ??
+                    existingSource.id;
+                const requestedEntities = entities.map((entity) => {
+                    const raw = { ...entity };
+                    const entityType = (typeof raw.entity_type === "string" && raw.entity_type) ||
+                        (typeof raw.type === "string" && raw.type) ||
+                        "";
+                    delete raw.entity_type;
+                    delete raw.type;
+                    return { entityType, fields: raw };
+                });
+                const requestedEntityTypes = new Set(requestedEntities.map((entity) => entity.entityType).filter(Boolean));
+                const { data: existingObservationRows, error: obsError } = await db
                     .from("observations")
-                    .select("id, entity_id, entity_type")
-                    .eq("source_id", existingSource.id)
+                    .select("id, entity_id, entity_type, fields, idempotency_key")
+                    .eq("source_id", observationSourceId)
                     .eq("user_id", userId);
                 if (obsError) {
                     throw new Error(`Failed to fetch existing observations: ${obsError.message}`);
                 }
-                const existingEntityIds = existingObservations?.map((obs) => obs.entity_id) ?? [];
+                const { getSnapshot: getSnapshotForReplay } = await import("./services/snapshot_computation.js");
+                let existingObservations = existingObservationRows ?? [];
+                if (observationSourceId !== existingSource.id && requestedEntityTypes.size > 0) {
+                    // Shared unstructured sources can host multiple same-typed
+                    // interpretations (plus siblings like audio_asset). Match against the
+                    // observation's stored fields / idempotency_key — never the current
+                    // entity snapshot, which drifts after correct() and used to fall open
+                    // to every same-typed row on the source (PR #2393 QA).
+                    const typeFiltered = existingObservations.filter((obs) => requestedEntityTypes.has(obs.entity_type));
+                    const keyMatched = typeFiltered.filter((obs) => typeof obs.idempotency_key === "string" && obs.idempotency_key === idempotencyKey);
+                    const fieldMatched = [];
+                    for (const obs of typeFiltered) {
+                        const obsFields = obs.fields && typeof obs.fields === "object"
+                            ? obs.fields
+                            : null;
+                        if (!obsFields)
+                            continue;
+                        const matches = requestedEntities.some((requested) => {
+                            if (requested.entityType && requested.entityType !== obs.entity_type) {
+                                return false;
+                            }
+                            return Object.entries(requested.fields).every(([key, value]) => obsFields[key] === value);
+                        });
+                        if (matches)
+                            fieldMatched.push(obs);
+                    }
+                    const resolved = keyMatched.length > 0 ? keyMatched : fieldMatched;
+                    if (resolved.length === 0 && typeFiltered.length >= 1) {
+                        throw new McpError(ErrorCode.InvalidParams, `ERR_IDEMPOTENCY_AMBIGUOUS: idempotency_key "${idempotencyKey}" matched a structured source whose interpretation source has ${typeFiltered.length} same-typed observation(s), but none match the requested fields or idempotency_key. Refusing to return sibling interpretations.`);
+                    }
+                    existingObservations = resolved;
+                }
+                const existingEntityIds = existingObservations.map((obs) => obs.entity_id) ?? [];
                 const relatedData = await this.getRelatedEntitiesAndRelationships(existingEntityIds);
                 const { data: fragmentRows } = await db
                     .from("raw_fragments")
@@ -4506,7 +4612,6 @@ export class NeotomaServer {
                 // one. No new observation is written, so we read the persisted snapshot
                 // directly. Mark each entry `deduplicated: true` so callers can tell a
                 // replay from a fresh write.
-                const { getSnapshot: getSnapshotForReplay } = await import("./services/snapshot_computation.js");
                 const replaySnapshotByEntityId = new Map();
                 for (const replayEntityId of new Set(existingEntityIds)) {
                     try {
@@ -4521,7 +4626,7 @@ export class NeotomaServer {
                 }
                 return this.buildTextResponse({
                     source_id: existingSource.id,
-                    entities: existingObservations?.map((obs) => ({
+                    entities: existingObservations.map((obs) => ({
                         entity_id: obs.entity_id,
                         entity_type: obs.entity_type,
                         observation_id: obs.id,
@@ -4579,6 +4684,7 @@ export class NeotomaServer {
                 userId,
                 sourceId: resolvedInterpretationSourceId,
                 extractedData: entities,
+                idempotencyKey,
                 config: {
                     provider: "agent",
                     model_id: "unknown",
@@ -5010,6 +5116,7 @@ export class NeotomaServer {
                     user_id: userId,
                     identity_basis: resolverTrace.identityBasis,
                     identity_rule: resolverTrace.identityRule,
+                    ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
                     ...(Object.keys(structuredAttribution).length > 0
                         ? { provenance: structuredAttribution }
                         : {}),