@4onstudios/iris-agent 0.1.0

package/dist/api/backendService.d.ts

@@ -0,0 +1,4 @@
+import type { RequestHandler } from "express";
+export declare const DEFAULT_BACKEND_SERVICE = "iris-agent";
+export declare const resolveBackendService: () => string;
+export declare const getBackendApiRouter: () => RequestHandler;

package/dist/api/backendService.js

@@ -0,0 +1,14 @@
+import agentRouter from "./agent.js";
+export const DEFAULT_BACKEND_SERVICE = "iris-agent";
+const normalizeBackendService = (value) => (value || DEFAULT_BACKEND_SERVICE).trim().toLowerCase();
+export const resolveBackendService = () => normalizeBackendService(process.env.IRIS_BACKEND_SERVICE);
+export const getBackendApiRouter = () => {
+    const backendService = resolveBackendService();
+    switch (backendService) {
+        case "iris-agent":
+            return agentRouter;
+        default:
+            console.warn(`[server] Unknown IRIS_BACKEND_SERVICE='${backendService}', falling back to '${DEFAULT_BACKEND_SERVICE}'.`);
+            return agentRouter;
+    }
+};

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

@@ -0,0 +1,82 @@
+export declare const AGENT_HOST_CONTRACT_VERSION = "1.0.0";
+export type AgentSource = "builtin" | "external";
+export type AgentCapability = "filesystem" | "workspace_search" | "terminal" | "lsp" | "mcp" | "tool_calling" | "streaming" | "approval_flow";
+export type AgentCapabilityMap = Partial<Record<AgentCapability, boolean>>;
+export type AgentPermissionScope = "workspace_read" | "workspace_write" | "workspace_delete" | "terminal_execute" | "network" | "lsp_request" | "mcp_request";
+export type AgentPermissionMode = "allow" | "deny" | "ask";
+export type AgentPermissionPolicy = Partial<Record<AgentPermissionScope, AgentPermissionMode>>;
+export type AgentDescriptor = {
+    id: string;
+    name: string;
+    version: string;
+    source: AgentSource;
+    description?: string;
+    capabilities?: AgentCapabilityMap;
+    permissions?: AgentPermissionPolicy;
+    tags?: string[];
+};
+export type AgentSessionContext = {
+    sessionId: string;
+    workspacePath: string;
+    modelId?: string;
+    metadata?: Record<string, unknown>;
+};
+export type AgentSession = {
+    sessionId: string;
+    agentId: string;
+    createdAt: number;
+};
+export type AgentTurnRequest = {
+    sessionId: string;
+    input: string;
+    conversation?: Array<{
+        role: "user" | "assistant" | "system" | "tool";
+        content: string;
+    }>;
+    metadata?: Record<string, unknown>;
+    onPreToolUse?: (input: {
+        toolName: string;
+        toolCallId?: string;
+        toolArgs?: Record<string, unknown>;
+    }) => Promise<void> | void;
+};
+export type AgentStreamEvent = {
+    type: "text-delta";
+    text: string;
+} | {
+    type: "tool-call";
+    name: string;
+    args?: Record<string, unknown>;
+} | {
+    type: "tool-result";
+    name: string;
+    result?: unknown;
+} | {
+    type: "approval-required";
+    reason: string;
+    payload?: Record<string, unknown>;
+} | {
+    type: "error";
+    message: string;
+} | {
+    type: "done";
+};
+export type AgentTurnResult = {
+    text: string;
+    toolCalls?: Array<Record<string, unknown>>;
+    toolResults?: Array<Record<string, unknown>>;
+    raw?: unknown;
+};
+export type AgentTurnStreamResult = {
+    stream: ReadableStream<AgentStreamEvent>;
+    getFinalResult: () => Promise<AgentTurnResult>;
+};
+export interface AgentRuntime {
+    readonly descriptor: AgentDescriptor;
+    startSession(context: AgentSessionContext): Promise<AgentSession>;
+    runTurn(request: AgentTurnRequest): Promise<AgentTurnResult>;
+    runTurnStream?(request: AgentTurnRequest): Promise<AgentTurnStreamResult>;
+    cancelTurn?(sessionId: string): Promise<void>;
+    endSession(sessionId: string): Promise<void>;
+}
+export type AgentRuntimeFactory<TRuntime = AgentRuntime> = () => Promise<TRuntime> | TRuntime;

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

@@ -0,0 +1 @@
+export const AGENT_HOST_CONTRACT_VERSION = "1.0.0";

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

@@ -0,0 +1,24 @@
+import type { AgentCapability, AgentDescriptor, AgentPermissionScope, AgentRuntime, AgentRuntimeFactory } from "./AgentContract.js";
+export type AgentSelectionPolicy = {
+    requiredCapabilities?: AgentCapability[];
+    requiredPermissions?: AgentPermissionScope[];
+};
+export declare class AgentRegistry<TRuntime = AgentRuntime> {
+    private readonly descriptors;
+    private readonly factories;
+    private defaultAgentId;
+    registerBuiltin(descriptor: AgentDescriptor, factory: AgentRuntimeFactory<TRuntime>, options?: {
+        asDefault?: boolean;
+    }): void;
+    registerExternal(descriptor: AgentDescriptor, factory: AgentRuntimeFactory<TRuntime>): void;
+    private register;
+    setDefaultAgent(agentId: string): void;
+    getDefaultAgentId(): string | null;
+    getDefaultAgentDescriptor(): AgentDescriptor | null;
+    getAgentDescriptor(agentId: string): AgentDescriptor | null;
+    listAgents(): AgentDescriptor[];
+    private satisfiesPolicy;
+    resolveAgentId(preferredAgentId?: string): string;
+    resolveAgentIdWithPolicy(preferredAgentId: string | undefined, policy: AgentSelectionPolicy): string;
+    createRuntime(preferredAgentId?: string, policy?: AgentSelectionPolicy): Promise<TRuntime>;
+}

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

@@ -0,0 +1,125 @@
+const ensureNonEmpty = (value, field) => {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error(`Agent descriptor requires a non-empty ${field}`);
+    }
+    return trimmed;
+};
+const normalizeDescriptor = (descriptor, expectedSource) => {
+    const id = ensureNonEmpty(descriptor.id, "id");
+    const name = ensureNonEmpty(descriptor.name, "name");
+    const version = ensureNonEmpty(descriptor.version, "version");
+    if (descriptor.source !== expectedSource) {
+        throw new Error(`Agent '${id}' has source '${descriptor.source}' but must be '${expectedSource}' in this registration path`);
+    }
+    return {
+        ...descriptor,
+        id,
+        name,
+        version,
+    };
+};
+export class AgentRegistry {
+    descriptors = new Map();
+    factories = new Map();
+    defaultAgentId = null;
+    registerBuiltin(descriptor, factory, options = {}) {
+        const normalized = normalizeDescriptor(descriptor, "builtin");
+        this.register(normalized, factory);
+        if (options.asDefault || this.defaultAgentId === null) {
+            this.defaultAgentId = normalized.id;
+        }
+    }
+    registerExternal(descriptor, factory) {
+        const normalized = normalizeDescriptor(descriptor, "external");
+        this.register(normalized, factory);
+    }
+    register(descriptor, factory) {
+        if (this.descriptors.has(descriptor.id)) {
+            throw new Error(`Agent '${descriptor.id}' is already registered`);
+        }
+        this.descriptors.set(descriptor.id, descriptor);
+        this.factories.set(descriptor.id, factory);
+    }
+    setDefaultAgent(agentId) {
+        const normalizedId = ensureNonEmpty(agentId, "agent id");
+        if (!this.descriptors.has(normalizedId)) {
+            throw new Error(`Cannot set default agent. Unknown agent '${normalizedId}'`);
+        }
+        this.defaultAgentId = normalizedId;
+    }
+    getDefaultAgentId() {
+        return this.defaultAgentId;
+    }
+    getDefaultAgentDescriptor() {
+        if (!this.defaultAgentId) {
+            return null;
+        }
+        return this.descriptors.get(this.defaultAgentId) || null;
+    }
+    getAgentDescriptor(agentId) {
+        const normalizedId = ensureNonEmpty(agentId, "agent id");
+        return this.descriptors.get(normalizedId) || null;
+    }
+    listAgents() {
+        return Array.from(this.descriptors.values());
+    }
+    satisfiesPolicy(descriptor, policy) {
+        if (!descriptor || !policy) {
+            return Boolean(descriptor);
+        }
+        const requiredCapabilities = policy.requiredCapabilities || [];
+        const requiredPermissions = policy.requiredPermissions || [];
+        if (requiredCapabilities.length > 0) {
+            const capabilities = descriptor.capabilities || {};
+            for (const capability of requiredCapabilities) {
+                if (capabilities[capability] !== true) {
+                    return false;
+                }
+            }
+        }
+        if (requiredPermissions.length > 0) {
+            const permissions = descriptor.permissions || {};
+            for (const scope of requiredPermissions) {
+                if (permissions[scope] === "deny") {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    resolveAgentId(preferredAgentId) {
+        const preferred = preferredAgentId?.trim();
+        if (preferred && this.descriptors.has(preferred)) {
+            return preferred;
+        }
+        if (this.defaultAgentId) {
+            return this.defaultAgentId;
+        }
+        throw new Error("No default agent is configured");
+    }
+    resolveAgentIdWithPolicy(preferredAgentId, policy) {
+        const preferred = preferredAgentId?.trim();
+        const preferredDescriptor = preferred ? this.descriptors.get(preferred) : undefined;
+        if (preferred && this.satisfiesPolicy(preferredDescriptor, policy)) {
+            return preferred;
+        }
+        if (this.defaultAgentId) {
+            const fallbackDescriptor = this.descriptors.get(this.defaultAgentId);
+            if (this.satisfiesPolicy(fallbackDescriptor, policy)) {
+                return this.defaultAgentId;
+            }
+        }
+        throw new Error("No eligible agent is configured for the requested policy");
+    }
+    async createRuntime(preferredAgentId, policy) {
+        const agentId = policy
+            ? this.resolveAgentIdWithPolicy(preferredAgentId, policy)
+            : this.resolveAgentId(preferredAgentId);
+        const factory = this.factories.get(agentId);
+        if (!factory) {
+            throw new Error(`No runtime factory registered for agent '${agentId}'`);
+        }
+        return await Promise.resolve(factory());
+    }
+}

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

@@ -0,0 +1,15 @@
+import { AgentRegistry } from "./AgentRegistry.js";
+import type { AgentDescriptor, AgentRuntimeFactory } from "./AgentContract.js";
+export declare const IRIS_DEFAULT_AGENT_DESCRIPTOR: AgentDescriptor;
+type ExternalAgentRegistration<TRuntime> = {
+    id?: string;
+    name?: string;
+    description?: string;
+    runtimeFactory: AgentRuntimeFactory<TRuntime>;
+};
+type CreateDefaultAgentRegistryOptions<TRuntime> = {
+    irisFactory: AgentRuntimeFactory<TRuntime>;
+    externalRegistration?: ExternalAgentRegistration<TRuntime>;
+};
+export declare const createDefaultAgentRegistry: <TRuntime>({ irisFactory, externalRegistration, }: CreateDefaultAgentRegistryOptions<TRuntime>) => AgentRegistry<TRuntime>;
+export {};

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

@@ -0,0 +1,46 @@
+import { AgentRegistry } from "./AgentRegistry.js";
+export const IRIS_DEFAULT_AGENT_DESCRIPTOR = {
+    id: "iris",
+    name: "Iris",
+    version: "1.0.0",
+    source: "builtin",
+    description: "Default built-in Iris coding agent runtime",
+    capabilities: {
+        tool_calling: true,
+        streaming: true,
+        approval_flow: true,
+        workspace_search: true,
+        filesystem: true,
+        lsp: true,
+        mcp: true,
+    },
+};
+export const createDefaultAgentRegistry = ({ irisFactory, externalRegistration, }) => {
+    const registry = new AgentRegistry();
+    registry.registerBuiltin(IRIS_DEFAULT_AGENT_DESCRIPTOR, irisFactory, {
+        asDefault: true,
+    });
+    if (externalRegistration) {
+        const id = (externalRegistration.id || "external-agent").trim() || "external-agent";
+        const name = (externalRegistration.name || "External Agent").trim() || "External Agent";
+        registry.registerExternal({
+            id,
+            name,
+            version: "0.1.0",
+            source: "external",
+            description: externalRegistration.description ||
+                "External agent registration hook.",
+            capabilities: {
+                tool_calling: true,
+                streaming: true,
+                approval_flow: true,
+                workspace_search: true,
+                filesystem: true,
+                lsp: true,
+                mcp: true,
+            },
+            tags: ["external"],
+        }, externalRegistration.runtimeFactory);
+    }
+    return registry;
+};

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

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import type { AgentDescriptor, AgentRuntimeFactory } from "./AgentContract.js";
+declare const manifestSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodDefault<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    modulePath: z.ZodString;
+    exportName: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    permissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["allow", "deny", "ask"]>>>;
+}, "strip", z.ZodTypeAny, {
+    description?: string;
+    id?: string;
+    name?: string;
+    version?: string;
+    modulePath?: string;
+    exportName?: string;
+    capabilities?: Record<string, boolean>;
+    permissions?: Record<string, "allow" | "deny" | "ask">;
+}, {
+    description?: string;
+    id?: string;
+    name?: string;
+    version?: string;
+    modulePath?: string;
+    exportName?: string;
+    capabilities?: Record<string, boolean>;
+    permissions?: Record<string, "allow" | "deny" | "ask">;
+}>;
+export type ExternalAgentManifest = z.infer<typeof manifestSchema>;
+export type ExternalAgentRuntimeContext = {
+    modelId: string;
+    workspacePath: string;
+    mcpServers: unknown[];
+};
+export type ExternalAgentRegistration<TRuntime> = {
+    descriptor: AgentDescriptor;
+    runtimeFactory: AgentRuntimeFactory<TRuntime>;
+};
+export declare class ExternalAgentLifecycleManager<TRuntime> {
+    private readonly manifestPath;
+    private manifestCache;
+    private moduleCache;
+    private lastHealthStatus;
+    constructor(manifestPath: string);
+    loadManifest(): Promise<ExternalAgentManifest>;
+    private loadModule;
+    healthCheck(): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    getLastHealthStatus(): {
+        ok: true;
+        checkedAt: number;
+    } | {
+        ok: false;
+        checkedAt: number;
+        reason: string;
+    } | null;
+    createRegistration(context: ExternalAgentRuntimeContext): Promise<ExternalAgentRegistration<TRuntime>>;
+}
+export {};

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

@@ -0,0 +1,117 @@
+import fs from "fs/promises";
+import path from "path";
+import { pathToFileURL } from "url";
+import { z } from "zod";
+const manifestSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    version: z.string().min(1).default("0.1.0"),
+    description: z.string().optional(),
+    modulePath: z.string().min(1),
+    exportName: z.string().optional(),
+    capabilities: z.record(z.string(), z.boolean()).optional(),
+    permissions: z.record(z.string(), z.enum(["allow", "deny", "ask"])).optional(),
+});
+const toCapabilities = (value) => {
+    if (!value)
+        return undefined;
+    return value;
+};
+const toPermissions = (value) => {
+    if (!value)
+        return undefined;
+    return value;
+};
+const resolveModuleFactory = (moduleNamespace, exportName) => {
+    const candidates = exportName
+        ? [exportName]
+        : ["createAgentRuntime", "default", "createRuntime"];
+    for (const candidate of candidates) {
+        const resolved = moduleNamespace[candidate];
+        if (typeof resolved === "function") {
+            return resolved;
+        }
+        const defaultNamespace = moduleNamespace.default;
+        if (defaultNamespace && typeof defaultNamespace === "object") {
+            const nested = defaultNamespace[candidate];
+            if (typeof nested === "function") {
+                return nested;
+            }
+        }
+    }
+    throw new Error(`External agent module is missing a runtime factory export. Checked: ${candidates.join(", ")}`);
+};
+export class ExternalAgentLifecycleManager {
+    manifestPath;
+    manifestCache = null;
+    moduleCache = null;
+    lastHealthStatus = null;
+    constructor(manifestPath) {
+        this.manifestPath = manifestPath;
+    }
+    async loadManifest() {
+        if (this.manifestCache) {
+            return this.manifestCache;
+        }
+        const raw = await fs.readFile(this.manifestPath, "utf8");
+        const parsed = manifestSchema.parse(JSON.parse(raw));
+        this.manifestCache = parsed;
+        return parsed;
+    }
+    async loadModule() {
+        if (this.moduleCache) {
+            return this.moduleCache;
+        }
+        const manifest = await this.loadManifest();
+        const baseDir = path.dirname(this.manifestPath);
+        const modulePath = path.isAbsolute(manifest.modulePath)
+            ? manifest.modulePath
+            : path.resolve(baseDir, manifest.modulePath);
+        const moduleUrl = pathToFileURL(modulePath).href;
+        const loaded = (await import(moduleUrl));
+        this.moduleCache = loaded;
+        return loaded;
+    }
+    async healthCheck() {
+        try {
+            const manifest = await this.loadManifest();
+            const moduleNamespace = await this.loadModule();
+            resolveModuleFactory(moduleNamespace, manifest.exportName);
+            this.lastHealthStatus = { ok: true, checkedAt: Date.now() };
+            return { ok: true };
+        }
+        catch (error) {
+            const err = error;
+            const reason = err.message || "Unknown external agent health-check failure";
+            this.lastHealthStatus = { ok: false, checkedAt: Date.now(), reason };
+            return { ok: false, reason };
+        }
+    }
+    getLastHealthStatus() {
+        return this.lastHealthStatus;
+    }
+    async createRegistration(context) {
+        const health = await this.healthCheck();
+        if (!health.ok) {
+            const reason = "reason" in health ? health.reason : "unknown";
+            throw new Error(`External agent failed health check: ${reason}`);
+        }
+        const manifest = await this.loadManifest();
+        const moduleNamespace = await this.loadModule();
+        const factory = resolveModuleFactory(moduleNamespace, manifest.exportName);
+        const descriptor = {
+            id: manifest.id,
+            name: manifest.name,
+            version: manifest.version,
+            source: "external",
+            description: manifest.description,
+            capabilities: toCapabilities(manifest.capabilities),
+            permissions: toPermissions(manifest.permissions),
+            tags: ["manifest", "external", "health-checked"],
+        };
+        return {
+            descriptor,
+            runtimeFactory: () => Promise.resolve(factory(context)),
+        };
+    }
+}

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

@@ -0,0 +1,111 @@
+import type { AgentRuntime, AgentRuntimeFactory, AgentSessionContext, AgentTurnRequest, AgentTurnResult, AgentTurnStreamResult } from "./AgentContract.js";
+export type HostPermissionRequestKind = "shell" | "read" | "write" | "mcp" | "custom-tool" | "factory" | "hook";
+export type HostPermissionRequest = {
+    kind: HostPermissionRequestKind;
+    intention?: string;
+    path?: string;
+    command?: string;
+    toolName?: string;
+    args?: Record<string, unknown>;
+    managedApprovalRequired?: boolean;
+    toolCallId?: string;
+};
+export type HostPermissionRequestResult = {
+    kind: "approve-once";
+} | {
+    kind: "reject";
+    feedback?: string;
+} | {
+    kind: "ask";
+    feedback?: string;
+} | {
+    kind: "user-not-available";
+} | {
+    kind: "no-result";
+};
+export type HostPermissionHandler = (request: HostPermissionRequest, invocation: {
+    sessionId: string;
+}) => Promise<HostPermissionRequestResult> | HostPermissionRequestResult;
+export type HostSessionHooks = {
+    onSessionStart?: (input: {
+        context: AgentSessionContext;
+    }, invocation: {
+        sessionId: string;
+    }) => Promise<void> | void;
+    onPreTurn?: (input: {
+        request: AgentTurnRequest;
+    }, invocation: {
+        sessionId: string;
+    }) => Promise<void> | void;
+    onPostTurn?: (input: {
+        request: AgentTurnRequest;
+        result: AgentTurnResult;
+    }, invocation: {
+        sessionId: string;
+    }) => Promise<void> | void;
+    onPreToolUse?: (input: {
+        toolName: string;
+        toolCallId?: string;
+        toolArgs?: Record<string, unknown>;
+        turnRequest: AgentTurnRequest;
+    }, invocation: {
+        sessionId: string;
+    }) => Promise<{
+        permissionDecision?: "allow" | "deny" | "ask";
+    } | null | void> | {
+        permissionDecision?: "allow" | "deny" | "ask";
+    } | null | void;
+    onPostToolUse?: (input: {
+        toolName: string;
+        toolCallId?: string;
+        toolResult?: unknown;
+        turnResult: AgentTurnResult;
+    }, invocation: {
+        sessionId: string;
+    }) => Promise<void> | void;
+    onSessionEnd?: (input: {
+        sessionId: string;
+    }, invocation: {
+        sessionId: string;
+    }) => Promise<void> | void;
+};
+export type HostSessionConfig = {
+    sessionId?: string;
+    modelId?: string;
+    metadata?: Record<string, unknown>;
+    onPermissionRequest?: HostPermissionHandler;
+    hooks?: HostSessionHooks;
+};
+export type HostSessionPromptRequest = {
+    prompt: string;
+    conversation?: AgentTurnRequest["conversation"];
+    metadata?: Record<string, unknown>;
+    permissionRequest?: HostPermissionRequest;
+};
+export type HostSessionHandle = {
+    sessionId: string;
+    sendAndWait: (request: HostSessionPromptRequest) => Promise<AgentTurnResult>;
+    sendStream: (request: HostSessionPromptRequest) => Promise<AgentTurnStreamResult>;
+    cancel: () => Promise<void>;
+    disconnect: () => Promise<void>;
+};
+export declare class HostSessionManager<TRuntime extends AgentRuntime> {
+    private readonly runtimeFactory;
+    private readonly baseContext;
+    private readonly sessions;
+    private readonly pendingSessions;
+    private stopping;
+    constructor(runtimeFactory: AgentRuntimeFactory<TRuntime>, baseContext: Omit<AgentSessionContext, "sessionId">);
+    createSession(config?: HostSessionConfig): Promise<HostSessionHandle>;
+    resumeSession(sessionId: string, config?: Omit<HostSessionConfig, "sessionId">): Promise<HostSessionHandle>;
+    private openSession;
+    private startSession;
+    private toHandle;
+    private getManagedSession;
+    private enforcePermission;
+    sendAndWait(sessionId: string, request: HostSessionPromptRequest): Promise<AgentTurnResult>;
+    sendStream(sessionId: string, request: HostSessionPromptRequest): Promise<AgentTurnStreamResult>;
+    disconnectSession(sessionId: string): Promise<void>;
+    cancelSession(sessionId: string): Promise<void>;
+    stopAll(): Promise<void>;
+}