Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
feat(server): record human handoff incidents (#40)
Leo3090ab8839ba
diff --git a/apps/server/src/bot-inbox/userActionIncidents.test.ts b/apps/server/src/bot-inbox/userActionIncidents.test.tsnew file mode 100644index 000000000..5fb595a7a--- /dev/null+++ b/apps/server/src/bot-inbox/userActionIncidents.test.ts@@ -0,0 +1,90 @@+// @effect-diagnostics nodeBuiltinImport:off+import * as NodeFS from "node:fs";+import * as NodeOS from "node:os";+import * as NodePath from "node:path";+import { afterEach, describe, expect, it } from "vite-plus/test";++import { BotId } from "@t3tools/contracts";++import { BotInboxService } from "./service.ts";+import { recordUserActionIncident, userActionIncidentKey } from "./userActionIncidents.ts";++const directories: string[] = [];++afterEach(() => {+ for (const directory of directories.splice(0)) {+ NodeFS.rmSync(directory, { recursive: true, force: true });+ }+});++function makeService() {+ const directory = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "akeru-user-action-inbox-"));+ directories.push(directory);+ const filePath = NodePath.join(directory, "bot-inbox.json");+ return { filePath, service: new BotInboxService(filePath) };+}++const input = {+ botId: BotId.make("bot-akeru"),+ botName: "Akeru",+ toolId: "request_box_help",+ summary: "Sign in to the bank site.",+ nextAction: "Open the bot workspace and complete the requested step.",+ target: "login",+};++describe("user-action inbox incidents", () => {+ it("records request_box_help on the existing inbox", () => {+ const { service } = makeService();+ const item = recordUserActionIncident(service, input);++ expect(item.incidentKey).toBe(+ userActionIncidentKey({ botId: input.botId, toolId: input.toolId, target: input.target }),+ );+ expect(item.kind).toBe("approval-request");+ expect(item.lastFailure).toBe(input.summary);+ expect(service.list().filter((candidate) => candidate.status === "open")).toEqual([item]);+ });++ it("deduplicates the same help request and keeps a later occurrence", () => {+ const { service } = makeService();+ const first = recordUserActionIncident(service, input);+ const second = recordUserActionIncident(service, {+ ...input,+ summary: "The login form is asking for a one-time code.",+ });++ expect(second.id).toBe(first.id);+ expect(second.occurrenceCount).toBe(2);+ expect(second.lastFailure).toBe("The login form is asking for a one-time code.");+ expect(service.list().filter((candidate) => candidate.status === "open")).toHaveLength(1);+ });++ it("opens a new incident for a different target", () => {+ const { service } = makeService();+ recordUserActionIncident(service, input);+ recordUserActionIncident(service, { ...input, target: "captcha" });++ expect(+ service+ .list()+ .filter((item) => item.status === "open")+ .map((item) => item.incidentKey)+ .sort(),+ ).toEqual([+ "user-action:bot-akeru:request_box_help:captcha",+ "user-action:bot-akeru:request_box_help:login",+ ]);+ });++ it("deduplicates after restart", () => {+ const { filePath, service } = makeService();+ const first = recordUserActionIncident(service, input);+ const restarted = new BotInboxService(filePath);+ const repeated = recordUserActionIncident(restarted, input);++ expect(repeated.id).toBe(first.id);+ expect(repeated.occurrenceCount).toBe(2);+ expect(new BotInboxService(filePath).list()).toEqual([repeated]);+ });+});diff --git a/apps/server/src/bot-inbox/userActionIncidents.ts b/apps/server/src/bot-inbox/userActionIncidents.tsnew file mode 100644index 000000000..7cc096407--- /dev/null+++ b/apps/server/src/bot-inbox/userActionIncidents.ts@@ -0,0 +1,40 @@+import type { BotId } from "@t3tools/contracts";++import type { BotInboxIncident, BotInboxItem, BotInboxService } from "./service.ts";++export interface UserActionIncidentInput {+ readonly botId: BotId;+ readonly botName: string;+ readonly toolId: string;+ readonly summary: string;+ readonly nextAction: string;+ readonly target?: string | null;+ readonly taskOrRoutine?: string;+}++export function userActionIncidentKey(input: {+ readonly botId: string;+ readonly toolId: string;+ readonly target?: string | null;+}): string {+ return `user-action:${input.botId}:${input.toolId}:${input.target ?? "-"}`;+}++export function toUserActionIncident(input: UserActionIncidentInput): BotInboxIncident {+ return {+ incidentKey: userActionIncidentKey(input),+ kind: "approval-request",+ botId: input.botId,+ botName: input.botName,+ taskOrRoutine: input.taskOrRoutine ?? input.toolId,+ lastFailure: input.summary,+ nextAction: input.nextAction,+ };+}++export function recordUserActionIncident(+ botInbox: BotInboxService,+ input: UserActionIncidentInput,+): BotInboxItem {+ return botInbox.upsert(toUserActionIncident(input));+}diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.tsindex 9488f35f4..f362272f3 100644--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts@@ -712,6 +712,7 @@ const make = Effect.gen(function* () {modelSelection: desiredModelSelection,mcpServers,...(respondingBotId ? { botId: respondingBotId } : {}),+ ...(respondingBot ? { botName: respondingBot.name } : {}),botSandbox: respondingBot?.sandbox ?? null,botSandboxBrowserSharing,...(input?.resumeCursor !== undefined ? { resumeCursor: input.resumeCursor } : {}),diff --git a/apps/server/src/provider/AkeruToolRuntime.test.ts b/apps/server/src/provider/AkeruToolRuntime.test.tsindex 689944d1c..e7dd5b3a7 100644--- a/apps/server/src/provider/AkeruToolRuntime.test.ts+++ b/apps/server/src/provider/AkeruToolRuntime.test.ts@@ -5,6 +5,7 @@ import * as NodePath from "node:path";import { LocalFilesystem, LocalSandbox, Workspace } from "@mastra/core/workspace";import { afterEach, describe, expect, it } from "vite-plus/test";+import { BotId } from "@t3tools/contracts";import { createAkeruToolRuntime } from "./AkeruToolRuntime.ts";@@ -119,6 +120,42 @@ describe("AkeruToolRuntime", () => {await expect(replacement.filesystem?.readFile(".env")).rejects.toThrow();});+ it("records a human handoff request", async () => {+ const requests: unknown[] = [];+ const runtime = createAkeruToolRuntime({+ onUserActionRequired: (request) => {+ requests.push(request);+ },+ });+ runtime.registerSession("thread-1", {+ botId: BotId.make("bot-one"),+ botName: "Research bot",+ runtimeMode: "full-access",+ workspaceType: "local",+ workspace: workspace("handoff"),+ });++ await expect(+ runtime.execute({+ threadId: "thread-1",+ toolId: "request_box_help",+ toolCallId: "tool-help",+ input: { reason: "captcha", message: "Complete the CAPTCHA." },+ approvalMode: "require-grant",+ }),+ ).resolves.toEqual({ requested: true });+ expect(requests).toEqual([+ {+ botId: "bot-one",+ botName: "Research bot",+ toolId: "request_box_help",+ summary: "Complete the CAPTCHA.",+ nextAction: "Open the bot workspace and complete the requested step.",+ target: "captcha",+ },+ ]);+ });+it("translates await handles to workspace process ids", async () => {const runtime = createAkeruToolRuntime();runtime.registerSession("thread-1", {diff --git a/apps/server/src/provider/AkeruToolRuntime.ts b/apps/server/src/provider/AkeruToolRuntime.tsindex a3e154077..01f8f587f 100644--- a/apps/server/src/provider/AkeruToolRuntime.ts+++ b/apps/server/src/provider/AkeruToolRuntime.ts@@ -2,6 +2,7 @@ import { RequestContext } from "@mastra/core/request-context";import { createWorkspaceTools, type Workspace } from "@mastra/core/workspace";import {AkeruToolInputSchemas,+ type BotId,type AkeruToolDefinition,type AkeruToolId,type AkeruToolWorkspaceType,@@ -12,13 +13,21 @@ import {} from "@t3tools/contracts";import * as Schema from "effect/Schema";+import type { UserActionIncidentInput } from "../bot-inbox/userActionIncidents.ts";+export interface AkeruToolSession {+ readonly botId?: BotId;+ readonly botName?: string;readonly runtimeMode: RuntimeMode;readonly workspaceType: AkeruToolWorkspaceType;readonly workspace?: Workspace;readonly userComputerWorkspace?: Workspace;}+export interface AkeruToolRuntimeOptions {+ readonly onUserActionRequired?: (input: UserActionIncidentInput) => void | Promise<void>;+}+export interface AkeruToolExecution {readonly threadId: string;readonly toolId: AkeruToolId;@@ -103,7 +112,7 @@ function executable(value: unknown): value is {);}-export function createAkeruToolRuntime(): AkeruToolRuntime {+export function createAkeruToolRuntime(options?: AkeruToolRuntimeOptions): AkeruToolRuntime {const sessions = new Map<string, AkeruToolSession>();const grants = new Map<string, { readonly toolId: AkeruToolId; readonly input: string }>();const key = (threadId: string, toolCallId: string) => `${threadId}\u0000${toolCallId}`;@@ -132,6 +141,9 @@ export function createAkeruToolRuntime(): AkeruToolRuntime {tools.add("CopyToBox");tools.add("CopyFromBox");}+ if (options?.onUserActionRequired && session.workspace && session.botId && session.botName) {+ tools.add("request_box_help");+ }return tools;};@@ -233,7 +245,18 @@ export function createAkeruToolRuntime(): AkeruToolRuntime {return { sourcePath, destinationPath };}if (input.toolId === "request_box_help") {- throw new Error("Human handoff is not available for this session.");+ if (!options?.onUserActionRequired || !session.botId || !session.botName) {+ throw new Error("Human handoff is not available for this session.");+ }+ await options.onUserActionRequired({+ botId: session.botId,+ botName: session.botName,+ toolId: input.toolId,+ summary: requiredString(decoded, "message"),+ nextAction: "Open the bot workspace and complete the requested step.",+ target: requiredString(decoded, "reason"),+ });+ return { requested: true };}const workspace = workspaceForTool(input.toolId, session);diff --git a/apps/server/src/provider/Layers/AgentController.test.ts b/apps/server/src/provider/Layers/AgentController.test.tsindex a4a720070..1153db245 100644--- a/apps/server/src/provider/Layers/AgentController.test.ts+++ b/apps/server/src/provider/Layers/AgentController.test.ts@@ -9,6 +9,7 @@ import { LocalFilesystem, LocalSandbox, Workspace } from "@mastra/core/workspaceimport {AKERU_PRODUCT_FEEDBACK_TOOL_NAME,ApprovalRequestId,+ BotId,EventId,McpServerId,ProviderDriverKind,@@ -26,6 +27,7 @@ import * as Stream from "effect/Stream";import { assert, describe, expect, vi } from "vite-plus/test";import { ServerConfig } from "../../config.ts";+import { BotInboxService } from "../../bot-inbox/service.ts";import { AgentController } from "../Services/AgentController.ts";import { LegacyProviderBridge } from "../Services/LegacyProviderBridge.ts";import type { ProviderServiceShape } from "../Services/ProviderService.ts";@@ -621,6 +623,75 @@ describe("AgentControllerLive", () => {);});+ it.effect("records human handoff requests in the bot inbox", () => {+ const bridge = makeBridge();+ const mastra = makeMastraHarness();+ const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "akeru-handoff-inbox-"));+ return provideController(+ Effect.gen(function* () {+ const controller = yield* AgentController;+ yield* resolveCodex(controller);+ const sessionInput = {+ threadId: codexThreadId,+ provider: ProviderDriverKind.make("codex"),+ providerInstanceId: codexInstanceId,+ modelSelection: codexSelection,+ botSandboxBrowserSharing: "shared" as const,+ runtimeMode: "full-access" as const,+ };+ yield* controller.startSession(codexThreadId, {+ ...sessionInput,+ botId: BotId.make("bot-one"),+ botName: "Research bot",+ });++ const runtime = mastra.harnessOptions[0]?.toolRuntime;+ assert.isDefined(runtime);+ yield* Effect.promise(() =>+ runtime.execute({+ threadId: String(codexThreadId),+ toolId: "request_box_help",+ toolCallId: "tool-help",+ input: { reason: "captcha", message: "Complete the CAPTCHA." },+ approvalMode: "require-grant",+ }),+ );++ expect(+ BotInboxService.forSecretsDir(NodePath.join(baseDir, "userdata", "secrets")).list(),+ ).toMatchObject([+ {+ botId: "bot-one",+ botName: "Research bot",+ taskOrRoutine: "request_box_help",+ lastFailure: "Complete the CAPTCHA.",+ },+ ]);+ yield* controller.startSession(codexThreadId, sessionInput);+ expect(runtime.toolsForThread(String(codexThreadId)).map((tool) => tool.id)).not.toContain(+ "request_box_help",+ );+ yield* Effect.promise(() =>+ expect(+ runtime.execute({+ threadId: String(codexThreadId),+ toolId: "request_box_help",+ toolCallId: "stale-handoff",+ input: { reason: "captcha", message: "Complete the CAPTCHA." },+ approvalMode: "require-grant",+ }),+ ).rejects.toThrow("Tool 'request_box_help' is not available for this turn."),+ );+ }),+ bridge.service,+ mastra.factory,+ undefined,+ baseDir,+ ).pipe(+ Effect.ensuring(Effect.sync(() => NodeFS.rmSync(baseDir, { recursive: true, force: true }))),+ );+ });+it.effect("grants one exact Akeru tool call without persisting acceptAlways", () => {const bridge = makeBridge();const mastra = makeMastraHarness();diff --git a/apps/server/src/provider/Layers/AgentController.ts b/apps/server/src/provider/Layers/AgentController.tsindex 804d9d3b4..30d4647cf 100644--- a/apps/server/src/provider/Layers/AgentController.ts+++ b/apps/server/src/provider/Layers/AgentController.ts@@ -36,6 +36,8 @@ import * as Semaphore from "effect/Semaphore";import * as Stream from "effect/Stream";import { resolveAttachmentPath } from "../../attachmentStore.ts";+import { BotInboxService } from "../../bot-inbox/service.ts";+import { recordUserActionIncident } from "../../bot-inbox/userActionIncidents.ts";import { ServerConfig } from "../../config.ts";import {SubscriptionAuthService,@@ -295,7 +297,12 @@ const make = (options?: AgentControllerLiveOptions) =>...(options?.makeRemoteWorkspace ? { makeRemoteWorkspace: options.makeRemoteWorkspace } : {}),...(options?.makeBotBrowser ? { makeBotBrowser: options.makeBotBrowser } : {}),});- const toolRuntime = createAkeruToolRuntime();+ const botInbox = BotInboxService.forSecretsDir(config.secretsDir);+ const toolRuntime = createAkeruToolRuntime({+ onUserActionRequired: (input) => {+ recordUserActionIncident(botInbox, input);+ },+ });const legacyResourceIdentity = new Map<string,{@@ -686,7 +693,15 @@ const make = (options?: AgentControllerLiveOptions) =>existing.providerInstanceId === resolved.providerInstanceId) {existing.runtimeMode = input.runtimeMode;- existing.toolSession = { ...existing.toolSession, runtimeMode: input.runtimeMode };+ const toolSession = { ...existing.toolSession };+ delete toolSession.botId;+ delete toolSession.botName;+ existing.toolSession = {+ ...toolSession,+ runtimeMode: input.runtimeMode,+ ...(input.botId ? { botId: input.botId } : {}),+ ...(input.botName ? { botName: input.botName } : {}),+ };toolRuntime.registerSession(key, existing.toolSession);return toProviderSession(threadId, existing);}@@ -755,6 +770,8 @@ const make = (options?: AgentControllerLiveOptions) =>);}const toolSession: AkeruToolSession = {+ ...(input.botId ? { botId: input.botId } : {}),+ ...(input.botName ? { botName: input.botName } : {}),runtimeMode: input.runtimeMode,workspaceType: resources.workspaceType,workspace: resources.workspace,diff --git a/packages/contracts/src/provider.test.ts b/packages/contracts/src/provider.test.tsindex b759c693f..49ae81c09 100644--- a/packages/contracts/src/provider.test.ts+++ b/packages/contracts/src/provider.test.ts@@ -65,10 +65,12 @@ describe("ProviderSessionStartInput", () => {threadId: "thread-1",provider: "codex",botId: "bot-one",+ botName: "Research bot",botSandboxBrowserSharing: "separate",runtimeMode: "full-access",});expect(parsed.botId).toBe("bot-one");+ expect(parsed.botName).toBe("Research bot");expect(parsed.botSandboxBrowserSharing).toBe("separate");});diff --git a/packages/contracts/src/provider.ts b/packages/contracts/src/provider.tsindex 50cb0f103..c29e03d8f 100644--- a/packages/contracts/src/provider.ts+++ b/packages/contracts/src/provider.ts@@ -67,6 +67,7 @@ export const ProviderSessionStartInput = Schema.Struct({approvalPolicy: Schema.optional(ProviderApprovalPolicy),sandboxMode: Schema.optional(ProviderSandboxMode),botId: Schema.optional(BotId),+ botName: Schema.optional(TrimmedNonEmptyString),botSandbox: Schema.optional(Schema.NullOr(BotSandbox)),botSandboxBrowserSharing: Schema.optional(BotSandboxBrowserSharing),mcpServers: Schema.optional(Schema.Array(McpServer)),