Skip to content

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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/workspace
import {
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.ts
index 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.ts
index 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.ts
index 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)),