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.
import type { AkeruToolResult } from "./tools/AkeruToolTypes.ts";
import * as Match from "effect/Match";
import * as Predicate from "effect/Predicate";
import { decodeAkeruRuntimeToolInput } from "./tools/AkeruToolInputs.ts";
import { RequestContext } from "@mastra/core/request-context";
import {
AKERU_TOOL_CATALOG,
type AkeruToolId,
type AkeruToolReceipt,
ThreadId,
akeruToolApprovalForInput,
akeruToolRequiresApproval,
filterAkeruTools,
AkeruDelegationContextTooLongError,
AkeruDelegationProviderUnsupportedError,
} from "@akeru/contracts";
import * as DateTime from "effect/DateTime";
import * as Schema from "effect/Schema";
import { redactComputerScreenshot } from "../mcp/PreviewSnapshotRedaction.ts";
import {
AKERU_MEMORY_TOOL_DESCRIPTION,
type AkeruMemoryToolId,
} from "../memory/BotMemoryToolHandlers.ts";
import {
type AkeruRuntimeToolDefinition,
type AkeruToolRuntimeOptions,
type AkeruToolRuntime,
type AkeruToolSession,
type AkeruRuntimeToolId,
type AkeruToolExecution,
} from "./tools/AkeruToolTypes.ts";
import {
ensureWorkspaceCwd,
APPROVAL_RANK,
canonicalInput,
requiredString,
field,
} from "./tools/AkeruToolAuthorization.ts";
import {
workspaceForTool,
toolsForWorkspace,
BACKEND_NAMES,
executable,
} from "./tools/AkeruWorkspaceTools.ts";
const isDelegationContextTooLong = Schema.is(AkeruDelegationContextTooLongError);
const isDelegationProviderUnsupported = Schema.is(AkeruDelegationProviderUnsupportedError);
const MEMORY_TOOL_DEFINITIONS = [
{ id: "memory", description: AKERU_MEMORY_TOOL_DESCRIPTION },
] as const satisfies ReadonlyArray<AkeruRuntimeToolDefinition>;
export function isMemoryToolId(toolId: string): toolId is AkeruMemoryToolId {
return toolId === "memory";
}
export function createAkeruToolRuntime(options?: AkeruToolRuntimeOptions): AkeruToolRuntime {
const sessions = new Map<string, AkeruToolSession>();
const grants = new Map<string, { readonly toolId: AkeruRuntimeToolId; readonly input: string }>();
const key = (threadId: string, toolCallId: string) => `${threadId}\u0000${toolCallId}`;
const clearApprovals = (threadId: string) => {
for (const grantKey of grants.keys()) {
if (grantKey.startsWith(`${threadId}\u0000`)) grants.delete(grantKey);
}
};
const emitReceipt = (
input: AkeruToolExecution,
phase: AkeruToolReceipt["phase"],
details?: Pick<AkeruToolReceipt, "failureCode" | "summary">,
) => {
try {
options?.onReceipt?.({
receiptId: input.toolCallId,
toolId: input.toolId,
phase,
threadId: ThreadId.make(input.threadId),
fatalToThread: false,
createdAt: DateTime.formatIso(DateTime.nowUnsafe()),
...details,
});
} catch {
// Receipt observers must not change tool execution.
}
};
const nonfatalToolFailureReceipt = (
input: AkeruToolExecution,
session: AkeruToolSession,
cause: unknown,
failureCode: NonNullable<AkeruToolReceipt["failureCode"]>,
billedBotId?: AkeruToolSession["botId"],
): AkeruToolReceipt => {
const summary = cause instanceof Error ? cause.message : String(cause);
const receipt = {
receiptId: input.toolCallId,
toolId: input.toolId,
phase: "failure",
threadId: ThreadId.make(input.threadId),
botId: session.botId,
summary,
failureCode,
fatalToThread: false,
...(billedBotId ? { billedBotId } : {}),
createdAt: options?.now?.() ?? DateTime.formatIso(DateTime.nowUnsafe()),
} satisfies AkeruToolReceipt;
emitReceipt(input, "failure", { failureCode, summary });
return receipt;
};
const implementedTools = (session: AkeruToolSession) => {
const tools = new Set<AkeruToolId>();
if (session.workspace?.sandbox?.executeCommand) tools.add("Shell");
if (session.workspace?.filesystem) tools.add("Read");
if (session.workspace?.sandbox?.processes) tools.add("AwaitShell");
if (session.workspace?.sandbox?.computer) tools.add("Screenshot");
if (session.userComputerWorkspace?.sandbox?.executeCommand) {
tools.add("ExternalShell");
}
if (session.userComputerWorkspace?.filesystem) {
tools.add("ExternalRead");
}
if (session.userComputerWorkspace?.sandbox?.processes) {
tools.add("AwaitExternalShell");
}
if (session.workspace?.filesystem && session.userComputerWorkspace?.filesystem) {
tools.add("CopyToBox");
tools.add("CopyFromBox");
}
if (options?.onUserActionRequired && session.workspace && session.botId && session.botName) {
tools.add("request_box_help");
}
if (session.delegation) {
if (session.delegation.create) tools.add("CreateAgent");
if (session.delegation.check) tools.add("CheckAgent");
tools.add("MessageAgent");
if (session.delegation.stop) tools.add("StopAgent");
tools.add("SendToAgent");
}
if (session.workers) {
tools.add("Task");
tools.add("CheckSubagent");
tools.add("MessageSubagent");
tools.add("StopSubagent");
}
if (session.channels) {
tools.add("CreateChannel");
tools.add("UpdateChannel");
}
if (session.sendToUser) tools.add("SendToUser");
if (session.botId && session.botState) tools.add("UpdateBotProfile");
if (session.reactToMessage) tools.add("ReactToMessage");
for (const { id: toolId } of AKERU_TOOL_CATALOG) {
if (!Object.hasOwn(session.catalogHandlers ?? {}, toolId)) continue;
if (toolId === "GenerateImage") {
const image = session.imageGeneration;
if (image && !image.chatgptEnabled && !image.grokEnabled) continue;
}
tools.add(toolId);
}
if (session.delegation) {
for (const toolId of tools) {
if (!session.delegation.access.allowedToolIds.includes(toolId)) tools.delete(toolId);
}
}
return tools;
};
const toolsForThread = (threadId: string) => {
const session = sessions.get(threadId);
if (!session) throw new Error(`Tool session '${threadId}' is not registered.`);
const implemented = implementedTools(session);
const workspaceTools = filterAkeruTools({
capabilities: new Set(["bot-workspace", "user-computer"]),
workspaceType: session.workspaceType,
hasUserComputer: Boolean(session.userComputerWorkspace),
localFullAccess: session.runtimeMode === "full-access",
implementedTools: implemented,
...(session.delegation
? {
delegationDepth: session.delegation.depth,
activeDelegations: session.delegation.activeDelegations,
}
: {}),
...(session.workers ? { workerDepth: session.workers.depth } : {}),
});
return session.memoryHandlers
? [...workspaceTools, ...MEMORY_TOOL_DEFINITIONS]
: workspaceTools;
};
const decodedGrantInput = (toolId: AkeruRuntimeToolId, input: AkeruToolExecution["input"]) =>
decodeAkeruRuntimeToolInput(toolId, input, { approvalGrant: true }).input;
const requiresApproval = async (
session: AkeruToolSession,
tool: AkeruRuntimeToolDefinition,
input: AkeruToolExecution["input"],
) => {
if (tool.id === "memory") return false;
const akeruTool = AKERU_TOOL_CATALOG.find((candidate) => candidate.id === tool.id);
if (!akeruTool) throw new Error(`Tool '${tool.id}' has no definition.`);
ensureWorkspaceCwd(akeruTool.id, input);
const ceiling = session.delegation?.access.approvalCeiling;
if (
ceiling &&
APPROVAL_RANK.indexOf(
akeruToolApprovalForInput(akeruTool, input, { workspaceType: session.workspaceType }),
) > APPROVAL_RANK.indexOf(ceiling)
) {
throw new Error(`Tool '${tool.id}' exceeds this delegation's approval ceiling.`);
}
return akeruToolRequiresApproval(
akeruTool,
{
localFullAccess: session.runtimeMode === "full-access",
workspaceType: session.workspaceType,
},
input,
);
};
return {
registerSession: (threadId, session) => {
clearApprovals(threadId);
sessions.set(threadId, session);
},
unregisterSession: (threadId) => {
sessions.delete(threadId);
clearApprovals(threadId);
},
clearApprovals,
toolsForThread,
requiresApproval: async (threadId, toolId, input) => {
const session = sessions.get(threadId);
if (!session) throw new Error(`Tool session '${threadId}' is not registered.`);
const tool = toolsForThread(threadId).find((candidate) => candidate.id === toolId);
if (!tool) throw new Error(`Tool '${toolId}' is not available for this turn.`);
return requiresApproval(session, tool, decodeAkeruRuntimeToolInput(toolId, input).input);
},
grantApproval: (input) => {
grants.set(key(input.threadId, input.toolCallId), {
toolId: input.toolId,
input: canonicalInput(decodedGrantInput(input.toolId, input.input)),
});
},
execute: async (input) => {
let failureCode: NonNullable<AkeruToolReceipt["failureCode"]> = "internal";
emitReceipt(input, "start");
let executionSession: AkeruToolSession | undefined;
try {
failureCode = "not_found";
const session = sessions.get(input.threadId);
if (!session) throw new Error(`Tool session '${input.threadId}' is not registered.`);
executionSession = session;
await options?.onToolStart?.(input, session);
const tool = toolsForThread(input.threadId).find(
(candidate) => candidate.id === input.toolId,
);
if (!tool) throw new Error(`Tool '${input.toolId}' is not available for this turn.`);
failureCode = "validation";
const execution = decodeAkeruRuntimeToolInput(input.toolId, input.input);
const decoded = execution.input;
failureCode = "denied";
if (await requiresApproval(session, tool, decoded)) {
const grantKey = key(input.threadId, input.toolCallId);
const grant = grants.get(grantKey);
if (
!grant ||
input.approvalMode !== "require-grant" ||
grant.toolId !== input.toolId ||
grant.input !== canonicalInput(decoded)
) {
throw new Error(`Tool '${input.toolId}' requires approval.`);
}
grants.delete(grantKey);
}
failureCode = "not_found";
let result: AkeruToolResult;
const catalogHandler =
execution.toolId === "memory" ? undefined : session.catalogHandlers?.[execution.toolId];
if (isMemoryToolId(input.toolId)) {
const handler = session.memoryHandlers?.[input.toolId];
if (!handler) throw new Error(`Tool '${input.toolId}' has no backend.`);
failureCode = "internal";
result = await handler({ ...input, toolId: input.toolId, input: decoded });
} else if (catalogHandler) {
failureCode = "internal";
result = await catalogHandler({
input: decoded,
emitProgress: (summary, details) =>
options?.onProgress?.({
threadId: input.threadId,
// SAFETY: Only catalog tools reach this callback; memory dispatch returns above.
toolId: input.toolId as AkeruToolId,
toolCallId: input.toolCallId,
summary,
...details,
}),
});
} else if (execution.toolId === "SendToAgent" || execution.toolId === "MessageAgent") {
if (!session.delegation) throw new Error("Delegation is not available for this session.");
const delegationInput = execution.input;
failureCode = "internal";
try {
result = await session.delegation.send(delegationInput);
} catch (cause) {
if (isDelegationContextTooLong(cause)) failureCode = "validation";
if (isDelegationProviderUnsupported(cause)) failureCode = "denied";
return nonfatalToolFailureReceipt(
input,
session,
cause,
failureCode,
delegationInput.botId,
);
}
} else if (
execution.toolId === "CreateAgent" ||
execution.toolId === "CheckAgent" ||
execution.toolId === "StopAgent"
) {
if (!session.delegation) {
throw new Error("Bot management is not available for this session.");
}
failureCode = "internal";
let billedBotId = session.botId;
try {
if (execution.toolId === "CreateAgent") {
if (!session.delegation.create) throw new Error("Bot creation is not available.");
result = await session.delegation.create(execution.input);
} else if (execution.toolId === "CheckAgent") {
if (!session.delegation.check) throw new Error("Bot inspection is not available.");
const checkInput = execution.input;
billedBotId = checkInput.botId;
result = await session.delegation.check(checkInput);
} else {
if (!session.delegation.stop) throw new Error("Bot cancellation is not available.");
const stopInput = execution.input;
billedBotId = stopInput.botId;
result = await session.delegation.stop(stopInput);
}
} catch (cause) {
return nonfatalToolFailureReceipt(input, session, cause, failureCode, billedBotId);
}
} else if (
execution.toolId === "Task" ||
execution.toolId === "CheckSubagent" ||
execution.toolId === "MessageSubagent" ||
execution.toolId === "StopSubagent"
) {
if (!session.workers) throw new Error("Workers are not available for this session.");
failureCode = "internal";
try {
result = await Match.value(execution).pipe(
Match.when({ toolId: "Task" }, ({ input }) => session.workers!.spawn(input)),
Match.when({ toolId: "CheckSubagent" }, ({ input }) => session.workers!.check(input)),
Match.when({ toolId: "MessageSubagent" }, ({ input }) =>
session.workers!.message(input),
),
Match.orElse(({ input }) => session.workers!.stop(input)),
);
} catch (cause) {
return nonfatalToolFailureReceipt(input, session, cause, failureCode);
}
} else if (execution.toolId === "CreateChannel" || execution.toolId === "UpdateChannel") {
if (!session.channels || !session.botId) {
throw new Error("Channel management is not available for this session.");
}
failureCode = "internal";
try {
const channelId =
execution.toolId === "CreateChannel"
? await session.channels.create(execution.input)
: await session.channels.update(execution.input);
result = {
receiptId: input.toolCallId,
toolId: input.toolId,
phase: "success",
threadId: ThreadId.make(input.threadId),
botId: session.botId,
summary: `Channel '${channelId}' saved.`,
fatalToThread: false,
billedBotId: session.botId,
createdAt: options?.now?.() ?? DateTime.formatIso(DateTime.nowUnsafe()),
} satisfies AkeruToolReceipt;
} catch (cause) {
const summary = cause instanceof Error ? cause.message : String(cause);
result = {
receiptId: input.toolCallId,
toolId: input.toolId,
phase: "failure",
threadId: ThreadId.make(input.threadId),
botId: session.botId,
summary,
failureCode,
fatalToThread: false,
billedBotId: session.botId,
createdAt: options?.now?.() ?? DateTime.formatIso(DateTime.nowUnsafe()),
} satisfies AkeruToolReceipt;
emitReceipt(input, "failure", { failureCode, summary });
return result;
}
} else if (execution.toolId === "SendToUser") {
if (!session.sendToUser) {
throw new Error("User messaging is not available for this session.");
}
failureCode = "internal";
try {
result = await session.sendToUser(execution.input);
} catch (cause) {
const summary = cause instanceof Error ? cause.message : String(cause);
result = {
receiptId: input.toolCallId,
toolId: input.toolId,
phase: "failure",
threadId: ThreadId.make(input.threadId),
botId: session.botId,
summary,
failureCode,
fatalToThread: false,
createdAt: options?.now?.() ?? DateTime.formatIso(DateTime.nowUnsafe()),
} satisfies AkeruToolReceipt;
emitReceipt(input, "failure", { failureCode, summary });
return result;
}
} else if (execution.toolId === "UpdateBotProfile") {
if (!session.botId || !session.botState) {
throw new Error("Bot profile management is not available for this session.");
}
failureCode = "internal";
try {
result = await session.botState.updateProfile(
ThreadId.make(input.threadId),
session.botId,
input.toolCallId,
execution.input,
);
} catch (cause) {
const summary = cause instanceof Error ? cause.message : String(cause);
result = {
receiptId: input.toolCallId,
toolId: input.toolId,
phase: "failure",
threadId: ThreadId.make(input.threadId),
botId: session.botId,
summary,
failureCode,
fatalToThread: false,
billedBotId: session.botId,
createdAt: options?.now?.() ?? DateTime.formatIso(DateTime.nowUnsafe()),
} satisfies AkeruToolReceipt;
emitReceipt(input, "failure", { failureCode, summary });
return result;
}
} else if (execution.toolId === "ReactToMessage") {
if (!session.reactToMessage) {
throw new Error("Message reactions are not available for this session.");
}
failureCode = "internal";
result = await session.reactToMessage(execution.input, input.toolCallId);
} else if (input.toolId === "CopyToBox" || input.toolId === "CopyFromBox") {
const source =
input.toolId === "CopyToBox" ? session.userComputerWorkspace : session.workspace;
const destination =
input.toolId === "CopyToBox" ? session.workspace : session.userComputerWorkspace;
if (!source?.filesystem || !destination?.filesystem) {
throw new Error("Both computer boundaries are required for file copy.");
}
const sourcePath = requiredString(decoded, "sourcePath");
const destinationPath = requiredString(decoded, "destinationPath");
failureCode = "internal";
await destination.filesystem.writeFile(
destinationPath,
await source.filesystem.readFile(sourcePath),
{ recursive: true },
);
result = { sourcePath, destinationPath };
} else if (input.toolId === "request_box_help") {
if (!options?.onUserActionRequired || !session.botId || !session.botName) {
throw new Error("Human handoff is not available for this session.");
}
failureCode = "internal";
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"),
});
result = { requested: true };
} else {
const workspace = workspaceForTool(input.toolId, session);
const backends = await toolsForWorkspace(workspace);
const backendNames = Object.hasOwn(BACKEND_NAMES, input.toolId)
? // SAFETY: hasOwn limits the tool id to the backend mapping keys.
BACKEND_NAMES[input.toolId as keyof typeof BACKEND_NAMES]
: [];
const backendName = backendNames.find((name) => executable(backends[name]));
const backend = backendName ? backends[backendName] : undefined;
if (!executable(backend)) throw new Error(`Tool '${input.toolId}' has no backend.`);
const backendInput =
input.toolId === "AwaitShell" || input.toolId === "AwaitExternalShell"
? { pid: requiredString(decoded, "handleId"), wait: true }
: decoded;
failureCode = "internal";
result = await backend.execute(backendInput, {
...(workspace ? { workspace } : {}),
requestContext: new RequestContext(),
observe: {
span: async <A>(_name: string, run: () => A | Promise<A>) => run(),
log: () => undefined,
},
});
}
if (input.toolId === "Screenshot") {
const mediaType = field(result, "mediaType");
const data = field(result, "data");
if (mediaType !== "image/png" || !Predicate.isString(data)) {
throw new Error("Screenshot result is invalid.");
}
const redacted = redactComputerScreenshot({
mediaType,
data: Buffer.from(data, "base64"),
});
result = {
...(Predicate.isObject(result) ? result : {}),
data: Buffer.from(redacted.data).toString("base64"),
};
}
if (field(result, "phase") === "failure") {
const summary = field(result, "summary");
emitReceipt(input, "failure", {
failureCode,
summary: Predicate.isString(summary) ? summary : "Tool execution failed.",
});
return result;
}
emitReceipt(input, "success");
return result;
} catch (cause) {
emitReceipt(input, "failure", { failureCode, summary: "Tool execution failed." });
throw cause;
} finally {
if (executionSession) await options?.onToolFinish?.(input, executionSession);
}
},
};
}
export {
type AkeruRuntimeToolId,
type AkeruRuntimeToolDefinition,
type AkeruToolSession,
type AkeruToolRuntimeOptions,
type AkeruToolExecution,
type AkeruToolRuntime,
} from "./tools/AkeruToolTypes.ts";
export { intersectDelegationAccess } from "./tools/AkeruToolAuthorization.ts";