Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/otel.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ Attributes on `lorekit.memory.*` spans:
| Attribute | Example | Notes |
|-----------|---------|-------|
| `lorekit.tool.name` | `memory.write` | Bounded set — safe as metric dimension |
| `auth.user_id` | `6e05fc90-…` | The caller's Supabase user UUID (pseudonymous), the same id the root request span and `usage_events.user_id` carry. Repeated here — and on the REST handler spans (`lorekit.memories.get/quota`, the write route, …) — because span metrics cannot join a child span to its parent: per-user counts of `lorekit.write.inserted` or `lorekit.memory.count` need the id on the span that holds them. **Omitted** for service-role callers, never empty. Guarded by `mcp-guards/tool-span-user-identity.spec.ts` |
| `lorekit.scope` | `repo::mthines/gw-tools` | Canonical scope string |
| `lorekit.scope.type` | `repo` | `global` \| `project` \| `repo` \| `branch` \| `mixed` (a multi-type `memory.search`, or a batch `memory.read` whose `refs` span several scope types) \| `invalid` (ungrammatical input). **Omitted entirely** when the operation carries no scope — never a placeholder. Resolved by the shared `scope-type-attribute.ts`. A batch read names its scopes inside `refs` rather than in a `scope` argument or query string, so MCP resolves them from the parsed refs and REST's handler reports the type to the router through `X-LoreKit-Scope-Type` — see "Scope attribution for body-carried scopes" below |
| `lorekit.key` | `aw-lessons::worktree-naming` | Lesson key |
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import path from 'node:path';

/**
* Source-scan drift guard: the caller's `auth.user_id` is stamped on the
* per-operation span, not only on the root request span.
*
* Both surfaces already put `auth.user_id` on their ROOT span (`lorekit.mcp`
* in `mcp/index.ts`, `lorekit.memories` / `lorekit.orgs` in
* `_shared/api/router.ts`). The facts a per-user view needs are written one
* level down, on the operation span:
*
* - MCP `lorekit.memory.write` — `lorekit.write.inserted`, `lorekit.source_agent`
* - MCP `lorekit.memory.quota` and REST `lorekit.memories.get/quota` —
* `lorekit.memory.count`, `lorekit.memory.limit`
*
* Span metrics (Dash0's `dash0.spans`, any spanmetrics connector) group one
* span's attributes at a time and cannot join a child to its parent, so
* without the id on the operation span "memories held per user" and "new
* memories per user" are unanswerable without a trace join.
*
* The edge tree has no test job, and the regression is missing telemetry, not
* a wrong value — nothing else in the suite goes red if a refactor drops it.
*/

const here = path.dirname(fileURLToPath(import.meta.url)); // packages/mcp-core/src/mcp-guards
const repoRoot = path.resolve(here, '../../../..');
const fnRoot = path.join(repoRoot, 'supabase', 'functions');

/** Executable lines only — mirrors `mcp-handler-plan-reuse.spec.ts`. */
const COMMENT_PREFIXES = ['//', '*', '/*', '*/'];
function executable(relPath: string): string {
return readFileSync(path.join(fnRoot, relPath), 'utf8')
.split('\n')
.map((line) => line.trim())
.filter((line) => line.length > 0)
.filter((line) => !COMMENT_PREFIXES.some((prefix) => line.startsWith(prefix)))
.join('\n');
}

const handler = executable('mcp/mcp-handler.ts');
const router = executable('_shared/api/router.ts');

describe('MCP tool span carries the caller (mcp/mcp-handler.ts)', () => {
// Anti-vacuity: a rename that made the span or the id unfindable must fail loudly.
it('still creates the tool span and still resolves analyticsUserId', () => {
expect(handler).toMatch(/const toolSpan = span\.child\(`lorekit\.\$\{toolName\}`/);
expect(handler).toMatch(/const analyticsUserId = /);
});

it('stamps auth.user_id on the tool span, guarded so it is absent rather than empty', () => {
expect(handler).toMatch(
/if \(analyticsUserId\) toolSpan\.setAttributes\(\{ 'auth\.user_id': analyticsUserId \}\);/,
);
});
});

describe('REST handler span carries the caller (_shared/api/router.ts)', () => {
it('still creates the handler span and still passes it to the route handler', () => {
expect(router).toMatch(/const hs = span\.child\(/);
expect(router).toContain('route.handler(req, resolved.auth, resolved.db, hs, params, cors)');
});

it('stamps auth.user_id on the handler span, guarded so it is absent rather than empty', () => {
expect(router).toMatch(
/if \(usageUserId !== null\) hs\.setAttributes\(\{ 'auth\.user_id': usageUserId \}\);/,
);
});
});

describe('no placeholder user id on either surface', () => {
it('never writes an empty or defaulted auth.user_id', () => {
for (const src of [handler, router]) {
expect(src).not.toMatch(/'auth\.user_id':\s*''/);
expect(src).not.toMatch(/'auth\.user_id':\s*[^,}]+\?\?\s*''/);
}
});
});
7 changes: 7 additions & 0 deletions supabase/functions/_shared/api/router.ts
Original file line number Diff line number Diff line change
Expand Up @@ -282,6 +282,13 @@ export function createRouter(routes: Route[], functionName: string) {
'auth.type': usageAuthType(resolved.auth),
...(usageUserId !== null ? { 'auth.user_id': usageUserId } : {}),
});
// ...and on the HANDLER span (`lorekit.memories.get/quota`, the write
// route, …), which is where handlers stamp what they learned —
// `lorekit.memory.count`, `lorekit.write.inserted`. A span-metric backend
// groups one span's attributes at a time and cannot join a child to its
// root, so the identity has to sit beside those facts for "memories per
// user" to be chartable. Same id, same absent-never-empty rule.
if (usageUserId !== null) hs.setAttributes({ 'auth.user_id': usageUserId });

// Only from the query string: the router must not consume the request
// body to peek at a scope, so body-carried scopes report null. Same
Expand Down
8 changes: 8 additions & 0 deletions supabase/functions/mcp/mcp-handler.ts
Original file line number Diff line number Diff line change
Expand Up @@ -380,6 +380,14 @@ export async function handleMcp(req: Request, auth: AuthContext, span: Span, ada
? await getUserPlanName(db, analyticsUserId, span)
: null;
if (planName) toolSpan.setAttributes({ 'lorekit.plan': planName });
// Caller identity on the TOOL span, not only on the root `lorekit.mcp`
// span (`mcp/index.ts`). The facts a per-user view needs live HERE —
// `lorekit.write.inserted`, `lorekit.memory.count`, `lorekit.source_agent`,
// `lorekit.scope.type` — and a span-metric backend cannot join a child
// span to its parent, so without the id on this span "new memories per
// user" or "memories held per user" is unanswerable without a trace join.
// Same id the usage event records; absent, never empty, for service-role.
if (analyticsUserId) toolSpan.setAttributes({ 'auth.user_id': analyticsUserId });

// Client-supplied grouping key (same header as the REST surface). Bounded by
// the pure validator; a malformed value degrades to null, never an error.
Expand Down
Loading