deepdebug-local-agent 1.13.0 → 1.13.1

package/docs/la-jobs-and-llm.md

@@ -13,7 +13,7 @@ the gateway's, synced by `scripts/sync-la-protocol-v2-contract.mjs`). The gatewa
 - Order: shape -> DLP enforce -> key held and alias in the key's models -> mask EVERY message (blocked class / DLP failure / oversize = refused, nothing sent) -> size and token budget -> concurrency slot -> call.
 - Limits: timeout per attempt, stream idle timeout, total deadline, <= 5 retries (network error, 408, 429, 5xx; `Retry-After` honoured, capped 10 s; never a 4xx, never after a delta was delivered), prompt bytes, output
   tokens, response bytes, concurrent calls (`busy`). Streaming (`stream:true`, `onDelta`) with `stream_options.include_usage`.
-- Tags: request `metadata.tags` = `vh-tenant:<id>`, `vh-la:<agent>`, `vh-job:<id>`, `vh-agent:<runner>` (ids only; `LOCAL_AGENT_LLM_TAGS=false` to omit). The key carries the same tenant/LA tags at the proxy. Whether LiteLLM merges request tags with key tags is NOT verified (fake server only).
+- Scope ids and tags (both routes, chat/completions and /v1/messages): request `metadata` = `vh_tenant_id` (this agent's session tenant), `vh_workspace_id` (the job's workspace, only when it is a plain id) and `tags` = `vh-tenant:<id>`, `vh-ws:<id>`, `vh-la:<agent>`, `vh-job:<id>`, `vh-agent:<runner>`, unique by value (`LOCAL_AGENT_LLM_TAGS=false` omits all of it). vh-litellm's scope-tag guard (enforce) rejects a `vh-tenant:` tag whose `vh_tenant_id` is missing or different (`tenant_tag_mismatch`), so the ids and the tags are always sent together. They never come from agent2 or a job payload. The key also carries `vh-tenant:`/`vh-la:` at the proxy, so LiteLLM sees the tenant tag twice (same value: the guard treats it as one). Whether LiteLLM merges as assumed is NOT verified (fake server with a port of the guard only).
 - Errors are codes only (`LlmClientError.code`, closed list in `client.js`); the body of an error response is never read. Usage comes from `usage`; without it the tokens are estimated (bytes/3) so a budget still counts. Cost from `x-litellm-response-cost` when present.
 - Local audit (ring, optional `LOCAL_AGENT_LLM_AUDIT_FILE`): alias, byte and token counts, per-rule redaction counts, short hash of the job id. Never a prompt, answer or key.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",

package/src/la-protocol-v2/jobs/manager.js

@@ -158,7 +158,7 @@ export function createJobManager({ session, tenantId, resolveWorkspace, material
         }
         async function llmCall(kind, opts) {
             if (rec.abortReason || rec.finished) throw new LlmClientError("cancelled");
-            const r = await llm.client[kind]({ ...opts, model: opts.model ?? rec.job.llm.alias, signal: rec.ac.signal, job: { jobId: rec.jobId, agent: theRunner.name }, tokensLeft: Math.max(0, rec.budget.tokens - tokensUsed(rec)) });
+            const r = await llm.client[kind]({ ...opts, model: opts.model ?? rec.job.llm.alias, signal: rec.ac.signal, job: { jobId: rec.jobId, agent: theRunner.name, workspaceId: rec.workspaceId }, tokensLeft: Math.max(0, rec.budget.tokens - tokensUsed(rec)) });
             rec.tokensIn += r.usage.promptTokens;
             rec.tokensOut += r.usage.completionTokens;
             if (r.costUsd !== null && r.costUsd !== undefined) rec.costUsd = (rec.costUsd || 0) + r.costUsd;

package/src/la-protocol-v2/llm/client.js

@@ -281,12 +281,32 @@ export function createLlmClient({ holder, config, tenantId, agentId, env = proce
         }));
     }
 
+    const SAFE_ID = /^[A-Za-z0-9_-]{1,64}$/;      // same rule as the agents' LiteLlmScopeTags: a crafted id must never smuggle a second tag
+    const SAFE_TAG_VALUE = /^[A-Za-z0-9._-]{1,64}$/;
+
+    /**
+     * The `metadata` of every LiteLLM request (chat/completions AND /v1/messages). vh-litellm's scope-tag guard needs the caller ids IN the body
+     * (`vh_tenant_id`, `vh_workspace_id`) and the scope tags to agree with them. The tenant is this agent's own (session); the workspace is the job's
+     * (the one this agent serves); nothing here comes from agent2 or a job payload. Tags are unique by value. null = nothing to send.
+     */
+    function requestMetadata(job) {
+        const md = {};
+        const tags = new Set();
+        if (SAFE_ID.test(String(tenantId))) { md.vh_tenant_id = String(tenantId); tags.add(`vh-tenant:${tenantId}`); }
+        const ws = typeof job?.workspaceId === "string" ? job.workspaceId.trim() : "";
+        if (md.vh_tenant_id && SAFE_ID.test(ws)) { md.vh_workspace_id = ws; tags.add(`vh-ws:${ws}`); }
+        if (SAFE_TAG_VALUE.test(String(agentId))) tags.add(`vh-la:${agentId}`);
+        if (job?.jobId && SAFE_TAG_VALUE.test(String(job.jobId))) tags.add(`vh-job:${job.jobId}`);
+        if (job?.agent && /^[a-z0-9][a-z0-9._-]{0,31}$/.test(job.agent)) tags.add(`vh-agent:${job.agent}`);
+        return { ...md, tags: [...tags] };
+    }
+
     /** The slot, the HTTP call with its retries and the bookkeeping, shared by chat() and messages(). `hooks` = { path, parseJson } of the API in use. */
     async function dispatch(o, ctx, hooks, makeBody) {
         if (active >= config.maxConcurrent) return fail("busy", ctx);
         active++;
         try {
-            const tags = config.tags ? { tags: [`vh-tenant:${tenantId}`, `vh-la:${agentId}`, ...(o.job?.jobId ? [`vh-job:${o.job.jobId}`] : []), ...(o.job?.agent && /^[a-z0-9][a-z0-9._-]{0,31}$/.test(o.job.agent) ? [`vh-agent:${o.job.agent}`] : [])] } : null;
+            const tags = config.tags ? requestMetadata(o.job) : null;
             const bodyText = makeBody(tags);
             stats.bytesOut += byteLength(bodyText);
             let attempts = 0;

package/test/la-protocol-v2/agent2-runner.test.js

@@ -84,7 +84,9 @@ test("job end to end: POST /jobs (local workspace, per-job token, options), the
     assert.equal(q.body.system[0].cache_control.type, "ephemeral", "prompt-cache markers go through");
     assert.ok(!q.raw.includes(GH), "DLP masked the token before it left");
     assert.ok(!q.raw.includes("vh_tier") && !q.headers["x-litellm-tags"], "agent2's own metadata and tags are not forwarded: the tags are the LA's");
-    assert.deepEqual(q.body.metadata.tags, [`vh-tenant:${TENANT}`, `vh-la:${r.link.session.agentId}`, `vh-job:${a.p.jobId}`, "vh-agent:agent2"]);
+    assert.deepEqual(q.body.metadata.tags, [`vh-tenant:${TENANT}`, "vh-ws:ws-1", `vh-la:${r.link.session.agentId}`, `vh-job:${a.p.jobId}`, "vh-agent:agent2"]);
+    assert.equal(q.body.metadata.vh_tenant_id, TENANT);
+    assert.equal(q.body.metadata.vh_workspace_id, "ws-1");
     assert.equal(job.record.llm.json.model, "vh-claude-sonnet", "the upstream model name is not handed to agent2");
     // what the control plane saw
     const evs = r.frames(a.p.jobId, "job.event");

package/test/la-protocol-v2/jobs-e2e.test.js

@@ -120,7 +120,8 @@ test("smoke job: ack accepted -> job.event running -> LLM call (file masked, key
     const q = r.fake.requests[0];
     assert.equal(q.headers.authorization, `Bearer ${r.key}`);
     assert.equal(q.body.model, "vh-claude-sonnet");
-    assert.deepEqual(q.body.metadata.tags, [`vh-tenant:${TENANT}`, `vh-la:${AGENT}`, `vh-job:${a.p.jobId}`, "vh-agent:smoke"]);
+    assert.equal(q.body.metadata.vh_workspace_id, "ws-1");
+    assert.deepEqual(q.body.metadata.tags, [`vh-tenant:${TENANT}`, "vh-ws:ws-1", `vh-la:${AGENT}`, `vh-job:${a.p.jobId}`, "vh-agent:smoke"]);
     const prompt = q.body.messages.map((m) => m.content).join("\n");
     assert.ok(prompt.includes(SMOKE_QUESTION) && prompt.includes(FILE_CANARY), "the (allowed) file is the subject of the fixed question");
     assert.ok(!q.raw.includes(GH), "the token inside the file was masked BEFORE leaving");

package/test/la-protocol-v2/llm-client.test.js

@@ -75,7 +75,7 @@ test("chat: OpenAI-compatible request (model, masked messages, max_tokens, tags)
     assert.equal(q.headers.authorization, `Bearer ${r.key}`);
     assert.equal(q.headers["content-type"], "application/json");
     assert.deepEqual(q.body, { model: "vh-claude-sonnet", messages: [msg("be brief", "system"), msg("what is this?")], max_tokens: 100, stream: false, temperature: 0,
-        metadata: { tags: [`vh-tenant:${TENANT}`, `vh-la:${AGENT}`, `vh-job:${JOB}`, "vh-agent:smoke"] } });
+        metadata: { vh_tenant_id: TENANT, tags: [`vh-tenant:${TENANT}`, `vh-la:${AGENT}`, `vh-job:${JOB}`, "vh-agent:smoke"] } });
     assert.ok(!q.raw.includes(r.key), "the key is never in a body");
     await r.close();
 });

package/test/la-protocol-v2/llm-messages.test.js

@@ -41,6 +41,8 @@ test("messages(): the request is /v1/messages with the key in the header, tags i
     assert.ok(!q.raw.includes(r.key));
     assert.deepEqual([q.body.model, q.body.max_tokens, q.body.temperature, q.body.tool_choice], ["vh-claude-sonnet", 100, 0, { type: "auto" }]);
     assert.deepEqual(q.body.system, [{ type: "text", text: "sys", cache_control: { type: "ephemeral" } }]);
+    assert.equal(q.body.metadata.vh_tenant_id, TENANT);
+    assert.equal(q.body.metadata.vh_workspace_id, undefined, "no workspace given: none claimed");
     assert.deepEqual(q.body.metadata.tags, [`vh-tenant:${TENANT}`, `vh-la:${AGENT}`, `vh-job:${JOB}`, "vh-agent:agent2"]);
     assert.deepEqual(out.usage, { promptTokens: 10, completionTokens: 4, estimated: false });
     assert.equal(out.costUsd, 0.002);

package/test/la-protocol-v2/llm-scope-ids.test.js

@@ -0,0 +1,129 @@
+// QA 2026-11-05: vh-litellm's scope-tag guard (enforce) rejected every Local Agent chat call with tenant_tag_mismatch: the LA sent the tag vh-tenant:<id>
+// but NOT vh_tenant_id / vh_workspace_id in the body. `guard()` below is a JS port of vh_plugins/scope_tags.py (collect + check); the fake gateway applies it to
+// what really arrives, on both routes. Not proven here: the real LiteLLM (how it merges key tags / request tags / litellm_metadata).
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import { createLlmKeyHolder } from "../../src/la-protocol-v2/llm-key/store.js";
+import { createLlmClient } from "../../src/la-protocol-v2/llm/client.js";
+import { resolveLlmClientConfig } from "../../src/la-protocol-v2/llm/config.js";
+import { startFakeLlm, closeAllFakes, okJson, okMessages, byPath, mkKey, keySet } from "./helpers/fake-llm.js";
+import { agent2Rig, TENANT, waitFor } from "./helpers/agent2-rig.js";
+
+after(closeAllFakes);
+const noop = () => {};
+const ENFORCE = { LOCAL_AGENT_DLP_MODE: "enforce" };
+const AGENT = "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d";
+
+// ---- port of vh_plugins/scope_tags.py
+const blank = (v) => v === null || v === undefined || (typeof v === "string" && !v.trim());
+const vals = (tags, prefix) => [...new Set(tags.filter((t) => typeof t === "string" && t.startsWith(prefix)).map((t) => t.slice(prefix.length).trim()))].sort();
+export function check(tags, tenantId, workspaceId) {
+    const tt = vals(tags, "vh-tenant:"), wt = vals(tags, "vh-ws:");
+    if (tt.length > 1) return "multiple_tenant_tags";
+    if (wt.length > 1) return "multiple_workspace_tags";
+    if (tt.length && (blank(tenantId) || tt[0] !== String(tenantId).trim())) return "tenant_tag_mismatch";
+    if (wt.length && (blank(workspaceId) || wt[0] !== String(workspaceId).trim())) return "workspace_tag_mismatch";
+    if (!blank(tenantId) && !tt.length) return "missing_tenant_tag";
+    if (!blank(workspaceId) && !wt.length) return "missing_workspace_tag";
+    return null;
+}
+export function collect(data) {
+    const tags = []; const ids = {};
+    for (const f of ["metadata", "litellm_metadata"]) {
+        const md = data[f];
+        if (!md || typeof md !== "object" || Array.isArray(md)) continue;
+        if (Array.isArray(md.tags)) tags.push(...md.tags);
+        for (const k of ["vh_tenant_id", "vh_workspace_id"]) if (blank(ids[k]) && !blank(md[k])) ids[k] = md[k];
+    }
+    if (Array.isArray(data.tags)) tags.push(...data.tags);
+    return [tags, ids.vh_tenant_id, ids.vh_workspace_id];
+}
+/** What the proxy does for /v1/messages: ids stay in `metadata`, the tags are also present in `litellm_metadata` (merged by the proxy), and the key's own tenant tag is added too (the duplicate seen in QA). */
+const asProxySees = (body, route, keyTags = []) => (route === "messages"
+    ? { ...body, litellm_metadata: { tags: [...(body.metadata?.tags || []), ...keyTags] } }
+    : { ...body, metadata: { ...body.metadata, tags: [...(body.metadata?.tags || []), ...keyTags] } });
+export const guard = (body, route, keyTags) => check(...collect(asProxySees(body, route, keyTags)));
+const KEY_TAGS = [`vh-tenant:${TENANT}`, `vh-la:${AGENT}`, "vh-dpm:x"];
+
+async function rig(tenantId = TENANT) {
+    const fake = await startFakeLlm(byPath({ chat: okJson("hi"), messages: okMessages("hi") }));
+    const key = mkKey();
+    const holder = createLlmKeyHolder({ log: { warn: noop } });
+    holder.set(keySet(key));
+    const config = { ...resolveLlmClientConfig({ LOCAL_AGENT_LLM_CLIENT: "true" }, noop), backoffMs: 0 };
+    const client = createLlmClient({ holder: { request: (p, i, o) => holder.request(p, i, o), describe: () => holder.describe(), get held() { return holder.held; } }, config, tenantId, agentId: AGENT, env: ENFORCE, fetchImpl: fake.fetchImpl });
+    return { fake, client };
+}
+const msgs = [{ role: "user", content: "go" }];
+
+test("the guard port rejects what QA rejected (tag without ids) and accepts the agreeing request", () => {
+    assert.equal(check([`vh-tenant:${TENANT}`, `vh-tenant:${TENANT}`], null, null), "tenant_tag_mismatch");
+    assert.equal(check([`vh-tenant:${TENANT}`, `vh-tenant:${TENANT}`], TENANT, null), null, "the same tag twice is one value");
+});
+
+for (const route of ["chat", "messages"]) {
+    test(`${route}: the request carries vh_tenant_id and vh_workspace_id and ONE tag each; the scope guard passes (with the key's tenant tag duplicated on top)`, async () => {
+        const r = await rig();
+        await r.client[route]({ model: "vh-claude-sonnet", messages: msgs, job: { jobId: "job-1", agent: "agent2", workspaceId: "ws-1" } });
+        const body = r.fake.requests[0].body;
+        assert.equal(body.metadata.vh_tenant_id, TENANT);
+        assert.equal(body.metadata.vh_workspace_id, "ws-1");
+        assert.equal(body.metadata.tags.filter((t) => t.startsWith("vh-tenant:")).length, 1);
+        assert.equal(body.metadata.tags.filter((t) => t.startsWith("vh-ws:")).length, 1);
+        assert.equal(new Set(body.metadata.tags).size, body.metadata.tags.length, "no duplicates");
+        assert.equal(guard(body, route, KEY_TAGS), null);
+        assert.equal(guard(body, route, []), null);
+        // before the fix: tags only, no ids
+        const old = { ...body, metadata: { tags: body.metadata.tags } };
+        assert.equal(guard(old, route, KEY_TAGS), "tenant_tag_mismatch");
+    });
+
+    test(`${route}: no workspace (or an unsafe one): the tenant is claimed, the workspace is not, no ws tag`, async () => {
+        const r = await rig();
+        await r.client[route]({ model: "vh-claude-sonnet", messages: msgs, job: { jobId: "job-1" } });
+        await r.client[route]({ model: "vh-claude-sonnet", messages: msgs, job: { jobId: "job-1", workspaceId: "ws-1,vh-tenant:evil" } });
+        for (const q of r.fake.requests) {
+            assert.equal(q.body.metadata.vh_tenant_id, TENANT);
+            assert.equal(q.body.metadata.vh_workspace_id, undefined);
+            assert.ok(!q.body.metadata.tags.some((t) => t.startsWith("vh-ws:") || t.includes("evil")));
+            assert.equal(guard(q.body, route, KEY_TAGS), null);
+        }
+    });
+}
+
+test("agent2 hostile through the bridge: its metadata, tags and headers (another tenant/workspace) are overwritten by the LA's own, on /v1/messages and /v1/chat/completions", async () => {
+    const r = await agent2Rig({ scenario: "stuck" });
+    const a = r.assign();
+    await a.acked();
+    await waitFor(() => r.fake.jobs.size === 1);
+    const job = r.fake.jobs.get(a.p.jobId);
+    const evil = { vh_tenant_id: "11111111-2222-3333-4444-555555555555", vh_workspace_id: "other-ws", tags: ["vh-tenant:11111111-2222-3333-4444-555555555555", "vh-ws:other-ws", "vh-tenant:" + TENANT] };
+    const headers = { authorization: `Bearer ${job.llm.key}`, "content-type": "application/json", "x-litellm-tags": "vh-tenant:11111111-2222-3333-4444-555555555555", "x-vh-tenant-id": "evil" };
+    const before = r.fakeLlm.requests.length;
+    const m = await fetch(`${r.bridgeBase}/v1/messages`, { method: "POST", headers, body: JSON.stringify({ model: "claude-x", max_tokens: 50, messages: msgs, metadata: evil, litellm_metadata: evil, tags: evil.tags }) });
+    const c = await fetch(`${r.bridgeBase}/v1/chat/completions`, { method: "POST", headers, body: JSON.stringify({ model: "gpt-x", messages: msgs, metadata: evil, tags: evil.tags }) });
+    assert.equal(m.status, 200); assert.equal(c.status, 200);
+    const sent = r.fakeLlm.requests.slice(before);
+    assert.equal(sent.length, 2);
+    for (const q of sent) {
+        const route = /\/messages$/.test(q.url) ? "messages" : "chat";
+        assert.equal(q.body.metadata.vh_tenant_id, TENANT);
+        assert.equal(q.body.metadata.vh_workspace_id, "ws-1");
+        assert.ok(!q.raw.includes("11111111-2222") && !q.raw.includes("other-ws") && !q.raw.includes("evil"), "nothing of agent2's claim leaves");
+        assert.equal(q.headers["x-litellm-tags"], undefined);
+        assert.equal(q.body.litellm_metadata, undefined);
+        assert.equal(q.body.tags, undefined);
+        assert.equal(new Set(q.body.metadata.tags).size, q.body.metadata.tags.length);
+        assert.equal(guard(q.body, route, KEY_TAGS), null);
+    }
+    await r.stop();
+});
+
+test("an unsafe tenant id claims nothing and tags nothing (never a smuggled tag)", async () => {
+    const r = await rig("t1,vh-tenant:evil");
+    await r.client.chat({ model: "vh-claude-sonnet", messages: msgs, job: { jobId: "j", workspaceId: "ws-1" } });
+    const md = r.fake.requests[0].body.metadata;
+    assert.equal(md.vh_tenant_id, undefined);
+    assert.equal(md.vh_workspace_id, undefined);
+    assert.ok(!md.tags.some((t) => t.startsWith("vh-tenant:") || t.startsWith("vh-ws:") || t.includes("evil")));
+});