@4onstudios/iris-agent 0.1.0

package/dist/api/core/agent/host/hostSessionManager.js

@@ -0,0 +1,352 @@
+import { randomUUID } from "node:crypto";
+import { getToolCallSignature } from "../utils/toolLifecycle.js";
+const asRecord = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+};
+const toAgentTurnRequest = (sessionId, request) => ({
+    sessionId,
+    input: request.prompt,
+    conversation: request.conversation,
+    metadata: request.metadata,
+});
+const getDeclaredToolCalls = (metadata) => {
+    const declared = metadata?.declaredToolCalls;
+    if (!Array.isArray(declared)) {
+        return [];
+    }
+    const parsed = [];
+    for (const item of declared) {
+        const value = asRecord(item);
+        const toolName = typeof value?.toolName === "string" ? value.toolName.trim() : "";
+        if (!toolName)
+            continue;
+        const toolCallId = typeof value?.toolCallId === "string" ? value.toolCallId : undefined;
+        const toolArgs = asRecord(value?.toolArgs);
+        parsed.push({ toolName, toolCallId, toolArgs });
+    }
+    return parsed;
+};
+const extractFeedback = (result) => {
+    if ((result.kind === "reject" || result.kind === "ask") && typeof result.feedback === "string") {
+        return result.feedback;
+    }
+    return undefined;
+};
+const enforceDeclaredToolHooks = async (hooks, turnRequest, invocation) => {
+    const declaredToolCalls = getDeclaredToolCalls(turnRequest.metadata);
+    for (const declared of declaredToolCalls) {
+        await turnRequest.onPreToolUse?.({
+            toolName: declared.toolName,
+            toolCallId: declared.toolCallId,
+            toolArgs: declared.toolArgs,
+        });
+    }
+};
+const createPreToolUseHook = (hooks, turnRequest, invocation) => {
+    const hasArgumentDetails = (toolArgs) => Object.keys(toolArgs || {}).length > 0;
+    const identifiedSignaturesByTool = new Map();
+    const getIdentifiedToolKey = (toolCallId, toolName) => `${toolCallId}:${toolName}`;
+    const registerIdentifiedSignature = (toolName, toolCallId, toolArgs) => {
+        if (!hasArgumentDetails(toolArgs))
+            return;
+        const toolKey = getIdentifiedToolKey(toolCallId, toolName);
+        const signatures = identifiedSignaturesByTool.get(toolKey) || new Set();
+        signatures.add(getToolCallSignature(toolName, toolArgs || {}));
+        identifiedSignaturesByTool.set(toolKey, signatures);
+    };
+    const getResolutionKeys = (toolName, toolCallId, toolArgs) => {
+        const signature = getToolCallSignature(toolName, toolArgs || {});
+        if (!toolCallId) {
+            return [`anonymous:${signature}`];
+        }
+        const genericKey = `${toolCallId}:${toolName}:generic`;
+        if (hasArgumentDetails(toolArgs)) {
+            registerIdentifiedSignature(toolName, toolCallId, toolArgs);
+            return [`${toolCallId}:${signature}`, genericKey];
+        }
+        const signatures = identifiedSignaturesByTool.get(getIdentifiedToolKey(toolCallId, toolName));
+        if (signatures && signatures.size === 1) {
+            const [onlySignature] = Array.from(signatures);
+            return [`${toolCallId}:${onlySignature}`, genericKey];
+        }
+        return [genericKey];
+    };
+    for (const declared of getDeclaredToolCalls(turnRequest.metadata)) {
+        if (declared.toolCallId) {
+            registerIdentifiedSignature(declared.toolName, declared.toolCallId, declared.toolArgs);
+        }
+    }
+    const declaredRemainingByKey = new Map();
+    for (const declared of getDeclaredToolCalls(turnRequest.metadata)) {
+        const [key] = getResolutionKeys(declared.toolName, declared.toolCallId, declared.toolArgs);
+        declaredRemainingByKey.set(key, (declaredRemainingByKey.get(key) || 0) + 1);
+    }
+    const declaredInvocationsByKey = new Map();
+    const reconciledRuntimeInvocationsByKey = new Map();
+    const approvedIdentifiedInvocations = new Set();
+    const invokeHook = async ({ toolName, toolCallId, toolArgs, }) => {
+        const result = await Promise.resolve(hooks?.onPreToolUse?.({ toolName, toolCallId, toolArgs, turnRequest }, invocation));
+        if (result && result.permissionDecision === "deny") {
+            throw new Error(`Tool '${toolName}' denied by onPreToolUse hook`);
+        }
+        if (result && result.permissionDecision === "ask") {
+            throw new Error(`Tool '${toolName}' requires external approval`);
+        }
+    };
+    return async ({ toolName, toolCallId, toolArgs }) => {
+        const keys = getResolutionKeys(toolName, toolCallId, toolArgs);
+        const primaryKey = keys[0];
+        const genericResolutionKey = toolCallId ? `${toolCallId}:${toolName}:generic` : undefined;
+        const runtimeProvidedArgumentDetails = hasArgumentDetails(toolArgs);
+        const declaredKeyToConsume = keys.find((key) => (declaredRemainingByKey.get(key) || 0) > 0);
+        if (declaredKeyToConsume) {
+            const declaredRemaining = declaredRemainingByKey.get(declaredKeyToConsume) || 0;
+            declaredRemainingByKey.set(declaredKeyToConsume, declaredRemaining - 1);
+            await invokeHook({ toolName, toolCallId, toolArgs });
+            declaredInvocationsByKey.set(declaredKeyToConsume, (declaredInvocationsByKey.get(declaredKeyToConsume) || 0) + 1);
+            return;
+        }
+        const keyToReconcile = keys.find((key) => {
+            if (runtimeProvidedArgumentDetails &&
+                genericResolutionKey &&
+                key === genericResolutionKey) {
+                return false;
+            }
+            const declaredInvocations = declaredInvocationsByKey.get(key) || 0;
+            const reconciledInvocations = reconciledRuntimeInvocationsByKey.get(key) || 0;
+            return reconciledInvocations < declaredInvocations;
+        });
+        if (keyToReconcile) {
+            const reconciledInvocations = reconciledRuntimeInvocationsByKey.get(keyToReconcile) || 0;
+            reconciledRuntimeInvocationsByKey.set(keyToReconcile, reconciledInvocations + 1);
+            return;
+        }
+        if (toolCallId && approvedIdentifiedInvocations.has(primaryKey)) {
+            return;
+        }
+        await invokeHook({ toolName, toolCallId, toolArgs });
+        if (toolCallId) {
+            approvedIdentifiedInvocations.add(primaryKey);
+        }
+    };
+};
+const runPostToolHooks = async (hooks, result, invocation) => {
+    const toolCalls = Array.isArray(result.toolCalls) ? result.toolCalls : [];
+    const toolResults = Array.isArray(result.toolResults) ? result.toolResults : [];
+    for (let index = 0; index < toolCalls.length; index += 1) {
+        const toolCall = asRecord(toolCalls[index]);
+        const toolName = typeof toolCall?.name === "string" && toolCall.name.trim().length > 0
+            ? toolCall.name
+            : "unknown_tool";
+        const toolCallId = typeof toolCall?.toolCallId === "string" ? toolCall.toolCallId : undefined;
+        await Promise.resolve(hooks?.onPostToolUse?.({
+            toolName,
+            toolCallId,
+            toolResult: index < toolResults.length ? toolResults[index] : undefined,
+            turnResult: result,
+        }, invocation));
+    }
+};
+export class HostSessionManager {
+    runtimeFactory;
+    baseContext;
+    sessions = new Map();
+    pendingSessions = new Map();
+    stopping = false;
+    constructor(runtimeFactory, baseContext) {
+        this.runtimeFactory = runtimeFactory;
+        this.baseContext = baseContext;
+    }
+    async createSession(config = {}) {
+        const sessionId = config.sessionId?.trim() || randomUUID();
+        return this.openSession(sessionId, config);
+    }
+    async resumeSession(sessionId, config = {}) {
+        const normalized = sessionId.trim();
+        if (!normalized) {
+            throw new Error("resumeSession requires a non-empty sessionId");
+        }
+        if (this.sessions.has(normalized)) {
+            return this.toHandle(normalized);
+        }
+        return this.openSession(normalized, { ...config, sessionId: normalized });
+    }
+    async openSession(sessionId, config) {
+        if (this.stopping) {
+            throw new Error("Host session manager is stopping");
+        }
+        if (this.sessions.has(sessionId)) {
+            return this.toHandle(sessionId);
+        }
+        const pending = this.pendingSessions.get(sessionId);
+        if (pending) {
+            return pending;
+        }
+        const opening = this.startSession(sessionId, config);
+        this.pendingSessions.set(sessionId, opening);
+        try {
+            return await opening;
+        }
+        finally {
+            this.pendingSessions.delete(sessionId);
+        }
+    }
+    async startSession(sessionId, config) {
+        const runtime = await Promise.resolve(this.runtimeFactory());
+        const context = {
+            sessionId,
+            workspacePath: this.baseContext.workspacePath,
+            modelId: config.modelId || this.baseContext.modelId,
+            metadata: {
+                ...(this.baseContext.metadata || {}),
+                ...(config.metadata || {}),
+            },
+        };
+        const invocation = { sessionId };
+        const session = await runtime.startSession(context);
+        try {
+            await Promise.resolve(config.hooks?.onSessionStart?.({ context }, invocation));
+            this.sessions.set(sessionId, { runtime, session, context, config });
+        }
+        catch (error) {
+            await runtime.endSession(sessionId).catch(() => undefined);
+            throw error;
+        }
+        return this.toHandle(sessionId);
+    }
+    toHandle(sessionId) {
+        return {
+            sessionId,
+            sendAndWait: async (request) => this.sendAndWait(sessionId, request),
+            sendStream: async (request) => this.sendStream(sessionId, request),
+            cancel: async () => this.cancelSession(sessionId),
+            disconnect: async () => this.disconnectSession(sessionId),
+        };
+    }
+    getManagedSession(sessionId) {
+        const managed = this.sessions.get(sessionId);
+        if (!managed) {
+            throw new Error(`Unknown session '${sessionId}'`);
+        }
+        return managed;
+    }
+    async enforcePermission(sessionId, config, request) {
+        if (!request || !config.onPermissionRequest) {
+            return;
+        }
+        const result = await Promise.resolve(config.onPermissionRequest(request, {
+            sessionId,
+        }));
+        if (result.kind === "reject" || result.kind === "user-not-available") {
+            throw new Error(extractFeedback(result) || "Permission request rejected");
+        }
+        if (result.kind === "ask" || result.kind === "no-result") {
+            throw new Error(extractFeedback(result) || "Permission request requires external resolution");
+        }
+    }
+    async sendAndWait(sessionId, request) {
+        const managed = this.getManagedSession(sessionId);
+        const invocation = { sessionId };
+        const turnRequest = toAgentTurnRequest(sessionId, request);
+        turnRequest.onPreToolUse = createPreToolUseHook(managed.config.hooks, turnRequest, invocation);
+        await this.enforcePermission(sessionId, managed.config, request.permissionRequest);
+        await Promise.resolve(managed.config.hooks?.onPreTurn?.({ request: turnRequest }, invocation));
+        await enforceDeclaredToolHooks(managed.config.hooks, turnRequest, invocation);
+        const result = await managed.runtime.runTurn(turnRequest);
+        await runPostToolHooks(managed.config.hooks, result, invocation);
+        await Promise.resolve(managed.config.hooks?.onPostTurn?.({ request: turnRequest, result }, invocation));
+        return result;
+    }
+    async sendStream(sessionId, request) {
+        const managed = this.getManagedSession(sessionId);
+        if (!managed.runtime.runTurnStream) {
+            throw new Error(`Agent '${managed.runtime.descriptor.id}' does not support runTurnStream`);
+        }
+        const invocation = { sessionId };
+        const turnRequest = toAgentTurnRequest(sessionId, request);
+        turnRequest.onPreToolUse = createPreToolUseHook(managed.config.hooks, turnRequest, invocation);
+        await this.enforcePermission(sessionId, managed.config, request.permissionRequest);
+        await Promise.resolve(managed.config.hooks?.onPreTurn?.({ request: turnRequest }, invocation));
+        await enforceDeclaredToolHooks(managed.config.hooks, turnRequest, invocation);
+        const streamResult = await managed.runtime.runTurnStream(turnRequest);
+        let finalizedResultPromise;
+        return {
+            ...streamResult,
+            stream: streamResult.stream,
+            getFinalResult: async () => {
+                if (!finalizedResultPromise) {
+                    finalizedResultPromise = (async () => {
+                        const finalResult = await streamResult.getFinalResult();
+                        await runPostToolHooks(managed.config.hooks, finalResult, invocation);
+                        await Promise.resolve(managed.config.hooks?.onPostTurn?.({ request: turnRequest, result: finalResult }, invocation));
+                        return finalResult;
+                    })();
+                }
+                return finalizedResultPromise;
+            },
+        };
+    }
+    async disconnectSession(sessionId) {
+        const managed = this.sessions.get(sessionId);
+        if (!managed) {
+            return;
+        }
+        this.sessions.delete(sessionId);
+        const errors = [];
+        try {
+            if (managed.runtime.cancelTurn) {
+                await managed.runtime.cancelTurn(sessionId);
+            }
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await Promise.resolve(managed.config.hooks?.onSessionEnd?.({ sessionId }, { sessionId }));
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        finally {
+            try {
+                await managed.runtime.endSession(sessionId);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length === 1) {
+            throw errors[0];
+        }
+        if (errors.length > 1) {
+            throw new AggregateError(errors, `Failed to disconnect host session '${sessionId}'`);
+        }
+    }
+    async cancelSession(sessionId) {
+        const managed = this.sessions.get(sessionId);
+        if (managed?.runtime.cancelTurn) {
+            await managed.runtime.cancelTurn(sessionId);
+        }
+    }
+    async stopAll() {
+        this.stopping = true;
+        for (const [sessionId, pending] of this.pendingSessions) {
+            void pending
+                .then(() => this.disconnectSession(sessionId))
+                .catch((error) => {
+                console.error(`Failed to clean up host session '${sessionId}' during shutdown:`, error);
+            });
+        }
+        const sessionIds = Array.from(this.sessions.keys());
+        const results = await Promise.allSettled(sessionIds.map((sessionId) => this.disconnectSession(sessionId)));
+        const errors = results
+            .filter((result) => result.status === "rejected")
+            .map((result) => result.reason);
+        if (errors.length > 0) {
+            throw new AggregateError(errors, "Failed to stop one or more host sessions");
+        }
+    }
+}

package/dist/api/core/agent/host/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./AgentContract.js";
+export * from "./AgentRegistry.js";
+export * from "./hostSessionManager.js";
+export * from "./defaultRegistry.js";
+export * from "./externalAgentLifecycle.js";

package/dist/api/core/agent/host/index.js

@@ -0,0 +1,5 @@
+export * from "./AgentContract.js";
+export * from "./AgentRegistry.js";
+export * from "./hostSessionManager.js";
+export * from "./defaultRegistry.js";
+export * from "./externalAgentLifecycle.js";

package/dist/api/core/agent/index.d.ts

@@ -0,0 +1,87 @@
+import { type ToolHooks } from "@mastra/core/tools";
+export declare const getSkillsDir: () => string;
+import { RequestContext } from "@mastra/core/request-context";
+import type { McpServerConfig } from "../library/mcpSettings.js";
+import type { TerminalAutoApproveRules } from "../library/terminalAutoApproveSettings.js";
+import { type ToolCallBudget } from "./utils/toolCallBudget.js";
+export { CODING_AGENT_INSTRUCTIONS, createIrisWorkspaceToolsConfig, } from "./publicContracts.js";
+export type AgentFactoryOptions = {
+    id?: string;
+    name?: string;
+    enableMemory?: boolean;
+    goalJudgeModelId?: string;
+    goalMaxRuns?: number;
+    useMastraObservationalMemory?: boolean;
+    observationalMemorySettings?: {
+        model?: string;
+        scope?: "resource" | "thread";
+        observationMessageTokens?: number;
+        reflectionObservationTokens?: number;
+        observationPreviousTokens?: number;
+        activateAfterIdle?: string;
+        activateOnProviderChange?: boolean;
+    };
+    storageId?: string;
+    dbUrl?: string;
+    vectorId?: string;
+    maxSteps?: number;
+    toolChoice?: "auto" | "none" | "required";
+    defaultOptions?: Record<string, unknown>;
+    mcpServers?: McpServerConfig[];
+    terminalAutoApproveRules?: TerminalAutoApproveRules;
+    hooks?: ToolHooks;
+    streamErrorRetry?: {
+        enabled?: boolean;
+        maxRetries?: number;
+        retryUnknownErrors?: boolean;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+    };
+};
+type AgentRequestContextValues = {
+    enabledSkills?: string[];
+    workspaceMutationGenerationId?: string;
+    toolCallBudget?: ToolCallBudget;
+    workspaceRoot?: string;
+    isWebWorkspace?: boolean;
+    gitDetected?: boolean;
+    modelId?: string;
+    contextFilesMeta?: Array<{
+        name?: string;
+        path?: string;
+        type?: string;
+        size?: number;
+        isImage?: boolean;
+    }>;
+    multimodalImageCount?: number;
+    onPreToolUse?: (input: {
+        toolName: string;
+        toolCallId?: string;
+        toolArgs?: Record<string, unknown>;
+    }) => Promise<void> | void;
+};
+export type AgentRequestValues = Omit<AgentRequestContextValues, "enabledSkills">;
+/**
+ * Invalidate the in-process skills cache so that the next call to
+ * `loadAllSkills` / `buildSkillsBlock` re-reads the skills directory.
+ * Intended for use in tests and development hot-reload scenarios.
+ */
+export declare function resetSkillsCache(): void;
+export declare const createAgentRequestContext: (enabledSkills?: string[], requestValues?: AgentRequestValues) => RequestContext<AgentRequestContextValues>;
+/**
+ * Return the canonical list of available skills for use by the
+ * `GET /api/agent/skills` endpoint. Each entry exposes the directory-name slug
+ * as `id` (matching what the client stores in preferences) and the description
+ * sourced directly from the SKILL.md frontmatter.
+ */
+export declare function getSkillsList(): Promise<Array<{
+    id: string;
+    description: string;
+}>>;
+export declare const createCodingAgent: (modelId?: string, workspacePath?: string | null, options?: AgentFactoryOptions) => Promise<import("@mastra/core/agent").Agent<string, import("@mastra/core/agent").ToolsInput, undefined, any, import("@mastra/core/agent").AgentEditorConfig> & {
+    takeProcessedWorkspaceResults: (generationId: string, toolCallIds: string[]) => {
+        toolCallId: string;
+        result: Record<string, unknown>;
+    }[];
+    clearProcessedWorkspaceResults: (generationId: string) => void;
+}>;