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
This commit is contained in:
1 parent
21df14cd00
commit
d011a2829c
15 files changed
+625
-3
No files matched your search
@@ -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\"\"",
|
||||
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
+99
-1
@@ -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<string, string | true>,
|
||||
): Promise<void> {
|
||||
@@ -277,6 +321,52 @@ async function handleReviewStats(
|
||||
}
|
||||
}
|
||||
|
||||
async function handleToolAuditList(
|
||||
flags: Map<string, string | true>,
|
||||
): Promise<void> {
|
||||
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<string, string | true>,
|
||||
): Promise<void> {
|
||||
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<void> {
|
||||
loadEnvironmentFromNodeEnv();
|
||||
initLogger();
|
||||
@@ -298,9 +388,17 @@ async function main(): Promise<void> {
|
||||
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.",
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -142,4 +142,71 @@ describe("runToolPlan", () => {
|
||||
toolName: "lookup-community-rule",
|
||||
});
|
||||
});
|
||||
|
||||
it("appends audit entries for successful tool calls", async () => {
|
||||
const streams: Array<{
|
||||
fields: Record<string, string>;
|
||||
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<string, string>,
|
||||
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));
|
||||
});
|
||||
});
|
||||
@@ -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<void> {
|
||||
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<string, ToolPlanStep>();
|
||||
@@ -278,19 +316,31 @@ async function runStep(input: {
|
||||
|
||||
const traceStep = getActiveProcessTrace()?.startStep("tool-call");
|
||||
let args: Record<string, unknown> = {};
|
||||
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,
|
||||
|
||||
@@ -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<string, unknown>)
|
||||
.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<string, string>,
|
||||
): 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<void> {
|
||||
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<ListedToolAuditEntry[]> {
|
||||
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<ListedToolAuditEntry | null> {
|
||||
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;
|
||||
}
|
||||
}
|
||||
@@ -93,6 +93,7 @@ export const lookupRuleTool: Tool<
|
||||
name: "lookup-rule",
|
||||
description:
|
||||
"광고, 도배, 욕설, 신고, 제재, 이의 제기, 개인정보 같은 moderation 규칙을 조회한다.",
|
||||
requires: ["memory-search"],
|
||||
argsSchema,
|
||||
resultSchema,
|
||||
async execute(args, ctx) {
|
||||
|
||||
@@ -41,6 +41,7 @@ export const checkOnboardingProgressTool: Tool<
|
||||
name: "check-onboarding-progress",
|
||||
description:
|
||||
"현재 유저의 온보딩 진행 상태를 읽어 카카오톡 단계와 디스코드 단계를 포함한 남은 절차를 구조화해서 반환한다.",
|
||||
requires: ["garnet", "user-session"],
|
||||
argsSchema,
|
||||
resultSchema,
|
||||
async execute(args, ctx) {
|
||||
|
||||
@@ -24,6 +24,7 @@ export const getRoomContextTool: Tool<
|
||||
name: "get-room-context",
|
||||
description:
|
||||
"최근 채팅방 대화를 조회해서 현재 유저 메시지가 다른 사람에게 향한 말인지, 방 분위기가 어떤지 판단할 수 있게 돕는다.",
|
||||
requires: ["room-context"],
|
||||
argsSchema,
|
||||
resultSchema,
|
||||
async execute(args, ctx) {
|
||||
|
||||
@@ -90,6 +90,7 @@ export const lookupCommunityRuleTool: Tool<
|
||||
name: "lookup-community-rule",
|
||||
description:
|
||||
"나이 제한, 닉네임 형식, 티어 코드, 하트 인증 규칙, 디스코드 안내 같은 커뮤니티 규칙을 조회한다.",
|
||||
requires: ["memory-search"],
|
||||
argsSchema,
|
||||
resultSchema,
|
||||
async execute(args, ctx) {
|
||||
|
||||
@@ -32,6 +32,7 @@ export const validateNicknameTool: Tool<
|
||||
name: "validate-nickname",
|
||||
description:
|
||||
"새내기 닉네임 형식이 이름/출생 연도/성별/티어 규칙에 맞는지 검사하고, 틀린 부분을 구조화해서 반환한다.",
|
||||
requires: [],
|
||||
argsSchema,
|
||||
resultSchema,
|
||||
execute(args) {
|
||||
|
||||
@@ -102,6 +102,7 @@ export const verifyDiscordNicknameTool: Tool<
|
||||
name: 'verify-discord-nickname',
|
||||
description:
|
||||
'현재 유저의 카카오톡 인증 닉네임과 세션 입장 시각을 기준으로 디스코드 멤버를 찾아, 닉네임 변경이 확인됐는지 구조화해서 반환한다.',
|
||||
requires: ['garnet', 'nats', 'user-session'],
|
||||
argsSchema,
|
||||
resultSchema,
|
||||
async execute(_args, ctx) {
|
||||
|
||||
@@ -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",
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -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<string, ToolPermission> = {
|
||||
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<T extends object>(
|
||||
target: T,
|
||||
key: string,
|
||||
toolName: string,
|
||||
permission: ToolPermission,
|
||||
): void {
|
||||
Object.defineProperty(target, key, {
|
||||
enumerable: true,
|
||||
get: () => deniedAccess(toolName, permission),
|
||||
});
|
||||
}
|
||||
|
||||
function buildScopedMemoryService(
|
||||
requires: ReadonlySet<ToolPermission>,
|
||||
fullContext: ToolContext,
|
||||
toolName: string,
|
||||
): MemoryService | undefined {
|
||||
if (!fullContext.memoryService) {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
const longTerm: Partial<LongTermMemory> = {};
|
||||
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<ToolPermission>,
|
||||
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;
|
||||
}
|
||||
@@ -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<A, R> {
|
||||
name: string;
|
||||
description: string;
|
||||
requires?: readonly ToolPermission[] | undefined;
|
||||
argsSchema: ZodType<A>;
|
||||
resultSchema: ZodType<R>;
|
||||
execute(args: A, ctx: ToolContext): Promise<R>;
|
||||
|
||||
Reference in new issue
Block a user