From d011a2829c051f980a7dc657be8ffb20faec67c7 Mon Sep 17 00:00:00 2001 From: dahyeon Date: Tue, 19 May 2026 01:27:03 -0700 Subject: [PATCH] Add tool permission sandbox and audit stream - Tool interface declares required permissions via requires field - scoped-context builds a least-privileged ToolContext per call - ToolAuditLogger appends each tool invocation to a Garnet stream - Operations CLI gains tool-audit:list and tool-audit:show commands - All onboarding and moderation tools annotated with explicit requires --- package.json | 2 + src/operations/cli.test.ts | 23 +++ src/operations/cli.ts | 100 +++++++++++- .../runtime/tool-plan-runner.test.ts | 67 ++++++++ .../onboarding/runtime/tool-plan-runner.ts | 74 ++++++++- src/tools/audit.ts | 135 ++++++++++++++++ src/tools/moderation/lookup-rule.ts | 1 + .../onboarding/check-onboarding-progress.ts | 1 + src/tools/onboarding/get-room-context.ts | 1 + src/tools/onboarding/lookup-community-rule.ts | 1 + src/tools/onboarding/validate-nickname.ts | 1 + .../onboarding/verify-discord-nickname.ts | 1 + src/tools/scoped-context.test.ts | 62 ++++++++ src/tools/scoped-context.ts | 149 ++++++++++++++++++ src/tools/tool.ts | 10 ++ 15 files changed, 625 insertions(+), 3 deletions(-) create mode 100644 src/tools/audit.ts create mode 100644 src/tools/scoped-context.test.ts create mode 100644 src/tools/scoped-context.ts diff --git a/package.json b/package.json index e059581..d23e43e 100644 --- a/package.json +++ b/package.json @@ -36,6 +36,8 @@ "review:show": "node --import tsx src/operations/cli.ts review:show", "review:resolve": "node --import tsx src/operations/cli.ts review:resolve", "review:stats": "node --import tsx src/operations/cli.ts review:stats", + "tool-audit:list": "node --import tsx src/operations/cli.ts tool-audit:list", + "tool-audit:show": "node --import tsx src/operations/cli.ts tool-audit:show", "start:dev": "pwsh -Command \"[System.Environment]::SetEnvironmentVariable('NODE_ENV', 'dev'); \"./launch-server.ps1\"\"", "start:test": "pwsh -Command \"[System.Environment]::SetEnvironmentVariable('NODE_ENV', 'test'); \"./launch-server.ps1\"\"", "start:prod": "pwsh -Command \"[System.Environment]::SetEnvironmentVariable('NODE_ENV', 'prod'); \"./launch-server.ps1\"\"", diff --git a/src/operations/cli.test.ts b/src/operations/cli.test.ts index 2848c93..746c4c0 100644 --- a/src/operations/cli.test.ts +++ b/src/operations/cli.test.ts @@ -4,6 +4,8 @@ import { formatReviewList, formatReviewShow, formatReviewStats, + formatToolAuditList, + formatToolAuditShow, } from "./cli.js"; describe("operations review CLI formatters", () => { @@ -81,4 +83,25 @@ describe("operations review CLI formatters", () => { }), ).toContain("low-confidence\ttotal=3\tpending=1\tresolved=2"); }); + + it("formats tool audit rows", () => { + const entry = { + argsHash: "abc123", + calledAt: "2026-05-18T00:00:00.000Z", + chatroomId: "room-1", + durationMs: 12, + id: "1-0", + ok: true, + resultSummary: "{\"ok\":true}", + skill: "onboarding", + toolName: "validate-nickname", + type: "tool-call" as const, + userId: "user-1", + }; + + expect(formatToolAuditList([entry])).toContain( + "1-0\t2026-05-18T00:00:00.000Z\tonboarding\tvalidate-nickname\tyes\t12", + ); + expect(formatToolAuditShow(entry)).toContain("argsHash: abc123"); + }); }); diff --git a/src/operations/cli.ts b/src/operations/cli.ts index db1067b..655530a 100644 --- a/src/operations/cli.ts +++ b/src/operations/cli.ts @@ -15,6 +15,10 @@ import { type SupervisorReviewResolution, type SupervisorReviewStats, } from "@skills/supervisor/review-queue"; +import { + ToolAuditLogger, + type ListedToolAuditEntry, +} from "@tools/audit"; import { getFlagString, hasFlag, @@ -164,6 +168,46 @@ export function formatReviewStats(stats: SupervisorReviewStats): string { ].join("\n"); } +export function formatToolAuditList(items: ListedToolAuditEntry[]): string { + const rows = [ + [ + "id", + "calledAt", + "skill", + "toolName", + "ok", + "durationMs", + "errorKind", + ], + ...items.map((item) => [ + item.id, + item.calledAt, + item.skill, + item.toolName, + item.ok ? "yes" : "no", + String(item.durationMs), + item.errorKind ?? "-", + ]), + ]; + return rows.map((row) => row.join("\t")).join("\n"); +} + +export function formatToolAuditShow(item: ListedToolAuditEntry): string { + return [ + `id: ${item.id}`, + `calledAt: ${item.calledAt}`, + `skill: ${item.skill}`, + `toolName: ${item.toolName}`, + `chatroomId: ${item.chatroomId}`, + `userId: ${item.userId}`, + `ok: ${item.ok ? "yes" : "no"}`, + `durationMs: ${item.durationMs}`, + `errorKind: ${item.errorKind ?? "-"}`, + `argsHash: ${item.argsHash}`, + `resultSummary: ${item.resultSummary || "-"}`, + ].join("\n"); +} + async function handleReviewList( flags: Map, ): Promise { @@ -277,6 +321,52 @@ async function handleReviewStats( } } +async function handleToolAuditList( + flags: Map, +): Promise { + const connection = await connectGarnetForCli(); + try { + const items = await new ToolAuditLogger(connection.garnetClient).list({ + limit: parsePositiveInteger(getFlagString(flags, "limit")) ?? 50, + since: sinceDurationToIso(getFlagString(flags, "since") ?? "24h"), + skill: getFlagString(flags, "skill"), + }); + console.info( + hasFlag(flags, "json") + ? JSON.stringify(items, null, 2) + : formatToolAuditList(items), + ); + } finally { + await connection.close(); + } +} + +async function handleToolAuditShow( + id: string | undefined, + flags: Map, +): Promise { + if (!id?.trim()) { + throw new Error("tool-audit:show requires an entry id"); + } + + const connection = await connectGarnetForCli(); + try { + const item = await new ToolAuditLogger(connection.garnetClient).get(id); + if (!item) { + process.exitCode = 2; + console.error(`[tool-audit] entry not found: ${id}`); + return; + } + console.info( + hasFlag(flags, "json") + ? JSON.stringify(item, null, 2) + : formatToolAuditShow(item), + ); + } finally { + await connection.close(); + } +} + async function main(): Promise { loadEnvironmentFromNodeEnv(); initLogger(); @@ -298,9 +388,17 @@ async function main(): Promise { await handleReviewStats(flags); return; } + if (command === "tool-audit:list") { + await handleToolAuditList(flags); + return; + } + if (command === "tool-audit:show") { + await handleToolAuditShow(positionals[0], flags); + return; + } throw new Error( - "Unknown command. Use review:list, review:show, review:resolve, or review:stats.", + "Unknown command. Use review:list, review:show, review:resolve, review:stats, tool-audit:list, or tool-audit:show.", ); } diff --git a/src/skills/onboarding/runtime/tool-plan-runner.test.ts b/src/skills/onboarding/runtime/tool-plan-runner.test.ts index e3ad343..779206d 100644 --- a/src/skills/onboarding/runtime/tool-plan-runner.test.ts +++ b/src/skills/onboarding/runtime/tool-plan-runner.test.ts @@ -142,4 +142,71 @@ describe("runToolPlan", () => { toolName: "lookup-community-rule", }); }); + + it("appends audit entries for successful tool calls", async () => { + const streams: Array<{ + fields: Record; + key: string; + options?: { maxLen?: number | undefined }; + }> = []; + const tool: Tool<{ topic: string }, { text: string }> = { + name: "lookup-community-rule", + description: "규칙 조회", + requires: [], + argsSchema: z.object({ + topic: z.string(), + }), + resultSchema: z.object({ + text: z.string(), + }), + execute: () => Promise.resolve({ text: "하트 규칙" }), + }; + + await runToolPlan( + { + composeWith: "all-then-llm", + steps: [ + { + id: "rule", + tool: "lookup-community-rule", + argsLiteral: { + topic: "heart", + }, + }, + ], + }, + [tool], + { + garnetClient: { + appendStream: ( + key: string, + fields: Record, + options?: { maxLen?: number | undefined }, + ) => { + streams.push({ + fields, + key, + ...(options ? { options } : {}), + }); + return Promise.resolve("1-0"); + }, + } as never, + }, + request(), + ); + + expect(streams[0]).toMatchObject({ + key: "lolympus-agent:tool-calls", + fields: { + ok: "true", + skill: "onboarding", + toolName: "lookup-community-rule", + type: "tool-call", + }, + options: { + maxLen: 100_000, + }, + }); + expect(streams[0]?.fields["argsHash"]).toEqual(expect.any(String)); + }); }); diff --git a/src/skills/onboarding/runtime/tool-plan-runner.ts b/src/skills/onboarding/runtime/tool-plan-runner.ts index 191a60c..1a6ead4 100644 --- a/src/skills/onboarding/runtime/tool-plan-runner.ts +++ b/src/skills/onboarding/runtime/tool-plan-runner.ts @@ -1,5 +1,8 @@ import type { AgentRequest } from "@agent/types"; +import { getRequestLogger } from "@obs/context"; import { withToolSpan } from "@obs/spans"; +import { hashToolArgs, ToolAuditLogger } from "@tools/audit"; +import { buildScopedContext } from "@tools/scoped-context"; import type { Tool, ToolContext, @@ -208,6 +211,41 @@ function makePlanFailure(message: string, details?: unknown): ToolExecutionFailu }); } +async function appendToolAudit(input: { + args: unknown; + ctx: ToolContext; + durationMs: number; + errorKind?: string | undefined; + ok: boolean; + request: AgentRequest; + resultSummary: string; + toolName: string; +}): Promise { + if (!input.ctx.garnetClient) { + return; + } + try { + await new ToolAuditLogger(input.ctx.garnetClient).append({ + type: "tool-call", + argsHash: hashToolArgs(input.args), + calledAt: new Date().toISOString(), + chatroomId: input.request.chatroomId, + durationMs: input.durationMs, + ...(input.errorKind ? { errorKind: input.errorKind } : {}), + ok: input.ok, + resultSummary: input.resultSummary, + skill: input.request.skill, + toolName: input.toolName, + userId: input.request.userId, + }); + } catch (error) { + getRequestLogger().warn( + { err: error, toolName: input.toolName }, + "[ToolAudit] Failed to append tool audit entry", + ); + } +} + function orderPlan(plan: ToolPlan): OrderedPlan { const failures: ToolExecutionFailure[] = []; const byId = new Map(); @@ -278,19 +316,31 @@ async function runStep(input: { const traceStep = getActiveProcessTrace()?.startStep("tool-call"); let args: Record = {}; + const startedAt = Date.now(); try { args = buildArgs(input); const validated = tool.argsSchema.parse(args); + const scopedContext = buildScopedContext(tool.requires, input.ctx, tool.name); const result = await withToolSpan( tool.name, { "tool.name": tool.name, "tool.plan.step_id": input.step.id, }, - () => tool.execute(validated, input.ctx), + () => tool.execute(validated, scopedContext), ); const structuredFailure = getStructuredFailure(input.step, result); if (structuredFailure) { + await appendToolAudit({ + args, + ctx: input.ctx, + durationMs: Math.max(0, Date.now() - startedAt), + errorKind: structuredFailure.kind, + ok: false, + request: input.request, + resultSummary: structuredFailure.message, + toolName: tool.name, + }); traceStep?.finish({ args, errorKind: structuredFailure.kind, @@ -302,15 +352,35 @@ async function runStep(input: { } input.results[input.step.id] = result; + const resultSummary = summarizeToolResult(result); + await appendToolAudit({ + args, + ctx: input.ctx, + durationMs: Math.max(0, Date.now() - startedAt), + ok: true, + request: input.request, + resultSummary, + toolName: tool.name, + }); traceStep?.finish({ args, name: tool.name, ok: true, - resultSummary: summarizeToolResult(result), + resultSummary, }); return null; } catch (error) { const failure = classifyError(tool.name, error); + await appendToolAudit({ + args, + ctx: input.ctx, + durationMs: Math.max(0, Date.now() - startedAt), + errorKind: failure.kind, + ok: false, + request: input.request, + resultSummary: failure.message, + toolName: tool.name, + }); traceStep?.finish({ args, errorKind: failure.kind, diff --git a/src/tools/audit.ts b/src/tools/audit.ts new file mode 100644 index 0000000..9a1a326 --- /dev/null +++ b/src/tools/audit.ts @@ -0,0 +1,135 @@ +import { createHash } from "node:crypto"; + +import type { GarnetClient } from "@common/garnet"; +import { getToolAuditMaxLen } from "../config.js"; + +export const TOOL_AUDIT_STREAM = "lolympus-agent:tool-calls"; + +export interface ToolAuditEntry { + type: "tool-call"; + toolName: string; + chatroomId: string; + userId: string; + argsHash: string; + resultSummary: string; + ok: boolean; + errorKind?: string | undefined; + durationMs: number; + skill: string; + traceId?: string | undefined; + calledAt: string; +} + +export interface ListedToolAuditEntry extends ToolAuditEntry { + id: string; +} + +function normalizeForHash(value: unknown): unknown { + if (Array.isArray(value)) { + return value.map(normalizeForHash); + } + if (typeof value !== "object" || value === null) { + return value; + } + + return Object.fromEntries( + Object.entries(value as Record) + .filter(([key]) => !/(password|secret|token|api[_-]?key|authorization)/iu.test(key)) + .sort(([left], [right]) => left.localeCompare(right)) + .map(([key, entry]) => [key, normalizeForHash(entry)]), + ); +} + +function asString(value: string | undefined): string | undefined { + return value?.trim() ? value : undefined; +} + +function parseAuditEntry( + id: string, + fields: Record, +): ListedToolAuditEntry | null { + if (fields["type"] !== "tool-call") { + return null; + } + return { + id, + type: "tool-call", + argsHash: fields["argsHash"] ?? "", + calledAt: fields["calledAt"] ?? "", + chatroomId: fields["chatroomId"] ?? "", + durationMs: Number(fields["durationMs"] ?? 0), + ...(asString(fields["errorKind"]) ? { errorKind: fields["errorKind"] } : {}), + ok: fields["ok"] === "true", + resultSummary: fields["resultSummary"] ?? "", + skill: fields["skill"] ?? "", + ...(asString(fields["traceId"]) ? { traceId: fields["traceId"] } : {}), + toolName: fields["toolName"] ?? "", + userId: fields["userId"] ?? "", + }; +} + +export function hashToolArgs(args: unknown): string { + return createHash("sha256") + .update(JSON.stringify(normalizeForHash(args))) + .digest("hex") + .slice(0, 16); +} + +export class ToolAuditLogger { + constructor( + private readonly garnetClient: Pick< + GarnetClient, + "appendStream" | "readStreamRange" + >, + ) {} + + async append(entry: ToolAuditEntry): Promise { + await this.garnetClient.appendStream( + TOOL_AUDIT_STREAM, + Object.fromEntries( + Object.entries(entry).map(([key, value]) => [key, String(value)]), + ), + { maxLen: getToolAuditMaxLen() }, + ); + } + + async list(opts: { + skill?: string | undefined; + since?: string | undefined; + limit?: number | undefined; + }): Promise { + const limit = Math.max(1, Math.min(opts.limit ?? 50, 500)); + const entries = await this.garnetClient.readStreamRange( + TOOL_AUDIT_STREAM, + "-", + "+", + { count: limit * 4 }, + ); + const sinceTime = opts.since ? Date.parse(opts.since) : NaN; + + return entries + .map((entry) => parseAuditEntry(entry.id, entry.message)) + .filter((entry): entry is ListedToolAuditEntry => entry !== null) + .filter((entry) => !opts.skill || entry.skill === opts.skill) + .filter((entry) => { + if (!Number.isFinite(sinceTime)) { + return true; + } + const calledAtTime = Date.parse(entry.calledAt); + return Number.isFinite(calledAtTime) && calledAtTime >= sinceTime; + }) + .slice(-limit) + .reverse(); + } + + async get(id: string): Promise { + const entries = await this.garnetClient.readStreamRange( + TOOL_AUDIT_STREAM, + id, + id, + { count: 1 }, + ); + const first = entries[0]; + return first ? parseAuditEntry(first.id, first.message) : null; + } +} diff --git a/src/tools/moderation/lookup-rule.ts b/src/tools/moderation/lookup-rule.ts index 4976f0a..ff1703a 100644 --- a/src/tools/moderation/lookup-rule.ts +++ b/src/tools/moderation/lookup-rule.ts @@ -93,6 +93,7 @@ export const lookupRuleTool: Tool< name: "lookup-rule", description: "광고, 도배, 욕설, 신고, 제재, 이의 제기, 개인정보 같은 moderation 규칙을 조회한다.", + requires: ["memory-search"], argsSchema, resultSchema, async execute(args, ctx) { diff --git a/src/tools/onboarding/check-onboarding-progress.ts b/src/tools/onboarding/check-onboarding-progress.ts index ffaf61e..10d1552 100644 --- a/src/tools/onboarding/check-onboarding-progress.ts +++ b/src/tools/onboarding/check-onboarding-progress.ts @@ -41,6 +41,7 @@ export const checkOnboardingProgressTool: Tool< name: "check-onboarding-progress", description: "현재 유저의 온보딩 진행 상태를 읽어 카카오톡 단계와 디스코드 단계를 포함한 남은 절차를 구조화해서 반환한다.", + requires: ["garnet", "user-session"], argsSchema, resultSchema, async execute(args, ctx) { diff --git a/src/tools/onboarding/get-room-context.ts b/src/tools/onboarding/get-room-context.ts index 278ca02..adb19fc 100644 --- a/src/tools/onboarding/get-room-context.ts +++ b/src/tools/onboarding/get-room-context.ts @@ -24,6 +24,7 @@ export const getRoomContextTool: Tool< name: "get-room-context", description: "최근 채팅방 대화를 조회해서 현재 유저 메시지가 다른 사람에게 향한 말인지, 방 분위기가 어떤지 판단할 수 있게 돕는다.", + requires: ["room-context"], argsSchema, resultSchema, async execute(args, ctx) { diff --git a/src/tools/onboarding/lookup-community-rule.ts b/src/tools/onboarding/lookup-community-rule.ts index 282757d..addcc23 100644 --- a/src/tools/onboarding/lookup-community-rule.ts +++ b/src/tools/onboarding/lookup-community-rule.ts @@ -90,6 +90,7 @@ export const lookupCommunityRuleTool: Tool< name: "lookup-community-rule", description: "나이 제한, 닉네임 형식, 티어 코드, 하트 인증 규칙, 디스코드 안내 같은 커뮤니티 규칙을 조회한다.", + requires: ["memory-search"], argsSchema, resultSchema, async execute(args, ctx) { diff --git a/src/tools/onboarding/validate-nickname.ts b/src/tools/onboarding/validate-nickname.ts index f7bec97..2946ee7 100644 --- a/src/tools/onboarding/validate-nickname.ts +++ b/src/tools/onboarding/validate-nickname.ts @@ -32,6 +32,7 @@ export const validateNicknameTool: Tool< name: "validate-nickname", description: "새내기 닉네임 형식이 이름/출생 연도/성별/티어 규칙에 맞는지 검사하고, 틀린 부분을 구조화해서 반환한다.", + requires: [], argsSchema, resultSchema, execute(args) { diff --git a/src/tools/onboarding/verify-discord-nickname.ts b/src/tools/onboarding/verify-discord-nickname.ts index b9d28f3..98ee2ff 100644 --- a/src/tools/onboarding/verify-discord-nickname.ts +++ b/src/tools/onboarding/verify-discord-nickname.ts @@ -102,6 +102,7 @@ export const verifyDiscordNicknameTool: Tool< name: 'verify-discord-nickname', description: '현재 유저의 카카오톡 인증 닉네임과 세션 입장 시각을 기준으로 디스코드 멤버를 찾아, 닉네임 변경이 확인됐는지 구조화해서 반환한다.', + requires: ['garnet', 'nats', 'user-session'], argsSchema, resultSchema, async execute(_args, ctx) { diff --git a/src/tools/scoped-context.test.ts b/src/tools/scoped-context.test.ts new file mode 100644 index 0000000..f27fcbf --- /dev/null +++ b/src/tools/scoped-context.test.ts @@ -0,0 +1,62 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { buildScopedContext } from "./scoped-context.js"; +import type { ToolContext } from "./tool.js"; + +describe("buildScopedContext", () => { + afterEach(() => { + vi.unstubAllEnvs(); + }); + + it("returns the full context when sandbox is disabled", () => { + const ctx: ToolContext = { + chatroomId: "room-1", + garnetClient: {} as ToolContext["garnetClient"], + }; + + expect(buildScopedContext([], ctx, "pure-tool")).toBe(ctx); + }); + + it("throws when sandboxed tools access undeclared permissions", () => { + vi.stubEnv("AGENT_TOOL_SANDBOX_ENABLED", "true"); + const ctx: ToolContext = { + chatroomId: "room-1", + garnetClient: {} as ToolContext["garnetClient"], + userId: "user-1", + }; + + const scoped = buildScopedContext([], ctx, "validate-nickname"); + + expect(scoped.chatroomId).toBe("room-1"); + expect(() => scoped.garnetClient).toThrow( + "Tool validate-nickname does not declare requires:garnet", + ); + }); + + it("exposes declared memory search without profile access", async () => { + vi.stubEnv("AGENT_TOOL_SANDBOX_ENABLED", "true"); + const search = vi.fn(() => Promise.resolve([])); + const ctx = { + memoryService: { + longTerm: { + search, + loadUserProfile: vi.fn(), + }, + session: {}, + assembleWorkingMemory: vi.fn(), + }, + } as unknown as ToolContext; + + const scoped = buildScopedContext( + ["memory-search"], + ctx, + "lookup-community-rule", + ); + + await scoped.memoryService?.longTerm.search("heart", { topK: 1 }); + expect(search).toHaveBeenCalledWith("heart", { topK: 1 }); + expect(() => scoped.memoryService?.longTerm.loadUserProfile("user-1")).toThrow( + "Tool lookup-community-rule does not declare requires:memory-profile", + ); + }); +}); diff --git a/src/tools/scoped-context.ts b/src/tools/scoped-context.ts new file mode 100644 index 0000000..14b90e3 --- /dev/null +++ b/src/tools/scoped-context.ts @@ -0,0 +1,149 @@ +import { getAgentToolSandboxEnabled } from "../config.js"; +import type { LongTermMemory, MemoryService } from "../memory/memory-types.js"; +import { getLogger } from "../observability/logger.js"; +import type { ToolContext, ToolPermission } from "./tool.js"; + +const PERMISSION_BY_FIELD: Record = { + garnetClient: "garnet", + memoryService: "memory-search", + natsClient: "nats", + roomContextService: "room-context", + session: "user-session", + toolRegistry: "tool-registry", +}; + +function deniedAccess(toolName: string, permission: ToolPermission): never { + throw new Error(`Tool ${toolName} does not declare requires:${permission}`); +} + +function defineDeniedGetter( + target: T, + key: string, + toolName: string, + permission: ToolPermission, +): void { + Object.defineProperty(target, key, { + enumerable: true, + get: () => deniedAccess(toolName, permission), + }); +} + +function buildScopedMemoryService( + requires: ReadonlySet, + fullContext: ToolContext, + toolName: string, +): MemoryService | undefined { + if (!fullContext.memoryService) { + return undefined; + } + + const longTerm: Partial = {}; + if (requires.has("memory-search")) { + longTerm.search = fullContext.memoryService.longTerm.search.bind( + fullContext.memoryService.longTerm, + ); + } else { + defineDeniedGetter(longTerm, "search", toolName, "memory-search"); + } + if (requires.has("memory-profile")) { + longTerm.loadUserProfile = + fullContext.memoryService.longTerm.loadUserProfile.bind( + fullContext.memoryService.longTerm, + ); + } else { + defineDeniedGetter(longTerm, "loadUserProfile", toolName, "memory-profile"); + } + + defineDeniedGetter(longTerm, "updateUserProfile", toolName, "memory-profile"); + defineDeniedGetter(longTerm, "upsertDocument", toolName, "memory-search"); + defineDeniedGetter(longTerm, "deleteDocument", toolName, "memory-search"); + + return { + longTerm: longTerm as LongTermMemory, + session: fullContext.memoryService.session, + assembleWorkingMemory: fullContext.memoryService.assembleWorkingMemory.bind( + fullContext.memoryService, + ), + }; +} + +function findUndeclaredContextPermissions( + requires: ReadonlySet, + fullContext: ToolContext, +): ToolPermission[] { + return [ + ...new Set( + Object.entries(PERMISSION_BY_FIELD) + .filter( + ([field, permission]) => + !requires.has(permission) && + fullContext[field as keyof ToolContext] !== undefined, + ) + .map(([, permission]) => permission), + ), + ]; +} + +export function buildScopedContext( + requires: readonly ToolPermission[] | undefined, + fullContext: ToolContext, + toolName = "unknown", +): ToolContext { + const sandboxEnabled = getAgentToolSandboxEnabled(); + if (!requires) { + if (sandboxEnabled) { + getLogger().warn( + { toolName }, + "[ToolSandbox] Tool has no requires declaration; using full context", + ); + } + return fullContext; + } + if (!sandboxEnabled) { + const undeclared = findUndeclaredContextPermissions( + new Set(requires), + fullContext, + ); + if (undeclared.length > 0) { + getLogger().warn( + { toolName, undeclared }, + "[ToolSandbox] Tool context includes undeclared permissions", + ); + } + return fullContext; + } + + const required = new Set(requires); + const scoped: ToolContext = { + chatroomId: fullContext.chatroomId, + userId: fullContext.userId, + }; + + if (required.has("garnet")) { + scoped.garnetClient = fullContext.garnetClient; + } + if (required.has("nats")) { + scoped.natsClient = fullContext.natsClient; + } + if (required.has("room-context")) { + scoped.roomContextService = fullContext.roomContextService; + } + if (required.has("tool-registry")) { + scoped.toolRegistry = fullContext.toolRegistry; + } + if (required.has("user-session")) { + scoped.session = fullContext.session; + } + if (required.has("memory-search") || required.has("memory-profile")) { + scoped.memoryService = buildScopedMemoryService(required, fullContext, toolName); + } + + for (const [field, permission] of Object.entries(PERMISSION_BY_FIELD)) { + if (field in scoped) { + continue; + } + defineDeniedGetter(scoped, field, toolName, permission); + } + + return scoped; +} diff --git a/src/tools/tool.ts b/src/tools/tool.ts index 240d683..f396efc 100644 --- a/src/tools/tool.ts +++ b/src/tools/tool.ts @@ -17,6 +17,15 @@ export interface ToolContext { toolRegistry?: ToolRegistry | undefined; } +export type ToolPermission = + | "garnet" + | "memory-profile" + | "memory-search" + | "nats" + | "room-context" + | "tool-registry" + | "user-session"; + export type ToolErrorKind = | "args-invalid" | "transient" @@ -34,6 +43,7 @@ export interface ToolExecutionFailure { export interface Tool { name: string; description: string; + requires?: readonly ToolPermission[] | undefined; argsSchema: ZodType; resultSchema: ZodType; execute(args: A, ctx: ToolContext): Promise;