@artinet/fleet 0.1.1 → 0.1.7

package/dist/server/express/server.js

@@ -2,25 +2,21 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import * as sdk from "@artinet/sdk";
-import express from "express";
-import { DEFAULTS } from "../../default.js";
-import * as agent from "./agent-request.js";
-import * as testing from "./test-request.js";
-import * as deployment from "./deploy-request.js";
-import { AGENT_FIELD_NAME } from "./agent-request.js";
+import * as sdk from '@artinet/sdk';
+import express from 'express';
+import { DEFAULTS } from '../../default.js';
+import * as agent from './agent-request.js';
+import * as testing from './test-request.js';
+import * as deployment from './deploy-request.js';
+import { AGENT_FIELD_NAME } from '../../default.js';
 const createContext = (settings) => {
     const _settings = {
         ...DEFAULTS,
         ...settings,
-        retrieve: agent.factory(settings.get ?? DEFAULTS.get, 
-        /**Middleware addons are currently only supported on the agent request route */
-        settings.middleware?.build() ?? []),
-        deploy: deployment.factory(settings.set ?? DEFAULTS.set),
-        evaluate: testing.factory(settings.test ?? DEFAULTS.test),
-        user: settings.user
-            ? settings.user
-            : (_req) => Promise.resolve(settings.userId ?? "default"),
+        retrieve: agent.factory({ implementation: settings.get ?? DEFAULTS.get }),
+        deploy: deployment.factory({ implementation: settings.set ?? DEFAULTS.set }),
+        evaluate: testing.factory({ implementation: settings.test ?? DEFAULTS.test }),
+        user: settings.user ? settings.user : (_session) => Promise.resolve(settings.userId ?? 'default'),
     };
     return _settings;
 };
@@ -40,9 +36,43 @@ const createRequestContext = (context) => {
         timestamp: undefined,
     };
 };
-export function fleet(settings = DEFAULTS, { app = express(), authOnRetrieve = false, enableTesting = true, } = {}) {
+/**
+ * Creates and configures a Fleet server instance using Express.
+ *
+ * This function implements the **Factory Pattern** combined with **Dependency Injection**
+ * to provide a flexible, testable, and configurable server setup. The pattern allows
+ * consumers to override defaults while maintaining sensible out-of-the-box behavior.
+ *
+ * @param settings - Partial configuration merged with defaults. Supports custom
+ *   handlers for `get`, `set`, `test`, and middleware composition.
+ * @param options - Server instantiation options
+ * @param options.app - Pre-configured Express application instance. Useful for
+ *   adding custom middleware or integrating with existing servers.
+ * @param options.authOnRetrieve - When `true`, applies auth middleware to agent
+ *   retrieval routes. Defaults to `false` for development convenience.
+ * @param options.enableTesting - When `true`, exposes the test endpoint for
+ *   agent evaluation. Disable in production if not needed.
+ *
+ * @returns Object containing:
+ *   - `app`: The configured Express application
+ *   - `launch`: Function to start the HTTP server on a specified port
+ *   - `ship`: Async function to deploy agents and return a launchable server
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with defaults
+ * const { app, launch } = fleet();
+ * launch(3000);
+ *
+ * // With custom configuration
+ * const { ship } = fleet({ userId: 'admin' }, { authOnRetrieve: true });
+ * const server = await ship([agentConfig]);
+ * server.launch(8080);
+ * ```
+ */
+export function fleet(settings = DEFAULTS, { app = express(), authOnRetrieve = false, enableTesting = true } = {}) {
     const context = createContext(settings);
-    const { basePath, agentPath, fallbackPath, deploymentPath, testPath, auth, user, evaluate, deploy, retrieve, set, } = context;
+    const { basePath, agentPath, fallbackPath, deploymentPath, testPath, auth, user, evaluate, deploy, retrieve, set } = context;
     const router = express.Router();
     router.use(express.json());
     if (auth) {
@@ -54,38 +84,32 @@ export function fleet(settings = DEFAULTS, { app = express(), authOnRetrieve = f
         }
     }
     if (enableTesting === true && evaluate !== undefined) {
-        router.post(testPath, async (req, res, next) => await testing.request({
-            request: req,
-            response: res,
-            next,
+        router.post(testPath, async (request, response, next) => await testing.request({
+            session: { request, response, next },
             context: createRequestContext(context),
             handler: evaluate,
             user,
         }), sdk.errorHandler);
     }
-    router.post(deploymentPath, async (req, res, next) => await deployment.request({
-        request: req,
-        response: res,
-        next,
+    router.post(deploymentPath, async (request, response, next) => await deployment.request({
+        session: { request, response, next },
         context: createRequestContext(context),
         handler: deploy,
         user,
     }));
-    router.use(`${agentPath}/:${AGENT_FIELD_NAME}`, async (req, res, next) => await agent.request({
-        request: req,
-        response: res,
-        next,
+    router.use(`${agentPath}/:${AGENT_FIELD_NAME}`, async (request, response, next) => await agent.request({
+        session: { request, response, next },
         context: createRequestContext(context),
         handler: retrieve,
         user,
+        intercepts: settings.middleware?.build() ?? [],
     }), sdk.errorHandler);
-    router.use(`${fallbackPath}/:${AGENT_FIELD_NAME}`, async (req, res, next) => await agent.request({
-        request: req,
-        response: res,
-        next,
+    router.use(`${fallbackPath}/:${AGENT_FIELD_NAME}`, async (request, response, next) => await agent.request({
+        session: { request, response, next },
         context: createRequestContext(context),
         handler: retrieve,
         user,
+        intercepts: settings.middleware?.build() ?? [],
     }), sdk.errorHandler);
     app.use(basePath, router);
     const launch = (port = 3000) => {
@@ -107,19 +131,3 @@ export function fleet(settings = DEFAULTS, { app = express(), authOnRetrieve = f
     };
     return { app, launch, ship };
 }
-// const swarm = await fleet().ship([
-//   {
-//     config: {
-//       uri: "my-agent",
-//       name: "my-agent",
-//       description: "A helpful assistant",
-//       modelId: "gpt-4",
-//       instructions: "You are a helpful assistant.",
-//       version: "1.0.0",
-//       skills: [],
-//       capabilities: {},
-//       services: [],
-//     },
-//   },
-// ]);
-// swarm.launch(3000);

package/dist/server/express/test-request.d.ts

@@ -2,17 +2,19 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import express from "express";
-import { TestAgentRoute } from "../../routes/request/index.js";
-export type handler = (req: express.Request, res: express.Response, next: express.NextFunction, context: TestAgentRoute["context"], test?: TestAgentRoute["implementation"]) => Promise<void>;
-export declare function handle(req: express.Request, res: express.Response, _next: express.NextFunction, context: TestAgentRoute["context"], test?: TestAgentRoute["implementation"]): Promise<void>;
-export declare const factory: (test?: TestAgentRoute["implementation"]) => handler;
-export interface Params {
-    request: express.Request;
-    response: express.Response;
-    next: express.NextFunction;
-    context: Omit<TestAgentRoute["context"], "agentId">;
-    handler: handler;
-    user: (request: express.Request) => Promise<string>;
-}
-export declare function request({ request: req, response: res, next, context, handler, user, }: Params): Promise<void>;
+import { TestAgentMount } from '../../routes/request/index.js';
+import { Session } from './types.js';
+/**
+ * Handler utilities for agent test/evaluation requests.
+ *
+ * Exports a reusable handler function for routing test/evaluation requests to agent instances,
+ * validating the request body, and returning the result as a JSON-RPC response.
+ *
+ * Used by the deployment server to provide a standard agent test/evaluation endpoint interface.
+ *
+ * @module server/handlers/test
+ */
+export type Mount = TestAgentMount<Session>;
+export declare const factory: Mount['factory'];
+export declare const handle: Mount['handler'];
+export declare const request: Mount['request'];

package/dist/server/express/test-request.js

@@ -2,25 +2,13 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import * as sdk from "@artinet/sdk";
-import { TestAgent, TestRequestSchema, } from "../../routes/request/index.js";
-import { v4 as uuidv4 } from "uuid";
-import { handleJSONRPCResponse } from "./rpc.js";
-import { generateRequestId } from "./utils.js";
-export async function handle(req, res, _next, context, test = TestAgent) {
-    let parsed = await sdk.validateSchema(TestRequestSchema, req?.body ?? {});
-    let id = parsed.id ?? uuidv4();
-    parsed.id = id;
-    let request = parsed;
-    context.target = parsed.config;
-    request.method = "test/invoke";
-    request.params = null;
-    const response = await test(request, context);
-    await handleJSONRPCResponse(res, String(id), request.method, response);
-}
-export const factory = (test = TestAgent) => async (req, res, next, context) => await handle(req, res, next, context, test);
+import * as sdk from '@artinet/sdk';
+import { TestAgent, TestRequestSchema, } from '../../routes/request/index.js';
+import { v4 as uuidv4 } from 'uuid';
+import { handleJSONRPCResponse } from './rpc.js';
+import { generateRequestId } from './utils.js';
 const MAX_TEST_ID_ATTEMPTS = 10;
-const getTestId = async (context) => {
+const generateTestId = async (context) => {
     let testId = uuidv4();
     let free = false;
     for (let i = 0; i < MAX_TEST_ID_ATTEMPTS; i++) {
@@ -40,12 +28,24 @@ const getTestId = async (context) => {
     }
     return testId;
 };
-export async function request({ request: req, response: res, next, context, handler = handle, user, }) {
-    const requestContext = {
+export const factory = ({ implementation = TestAgent }) => async (params) => await handle(params, implementation);
+export const handle = async ({ session: { request, response }, context }, implementation = TestAgent) => {
+    let parsed = await sdk.validateSchema(TestRequestSchema, request?.body ?? {});
+    let id = parsed.id ?? uuidv4();
+    parsed.id = id;
+    let req = parsed;
+    context.target = parsed.config;
+    req.method = 'test/invoke';
+    req.params = null;
+    const res = await implementation(req, context);
+    return await handleJSONRPCResponse(response, String(id), req.method, res);
+};
+export const request = async ({ session, context, handler = handle, user, intercepts }, implementation = TestAgent) => {
+    const _context = {
         ...context,
-        agentId: await getTestId(context),
-        requestId: generateRequestId(context, req),
-        userId: await user?.(req),
+        agentId: await generateTestId(context),
+        requestId: generateRequestId(context, session.request),
+        userId: await user?.(session),
     };
-    return await handler(req, res, next, requestContext);
-}
+    return await handler({ session, context: _context, intercepts }, implementation);
+};

package/dist/server/express/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import express from 'express';
+export type Session = {
+    request: express.Request;
+    response: express.Response;
+    next: express.NextFunction;
+};

package/dist/server/express/types.js

@@ -0,0 +1,5 @@
+/**
+ * Copyright 2025 The Artinet Project
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/server/hono/agent-request.d.ts

@@ -2,12 +2,8 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import * as hono from "hono";
-import { RequestAgentRoute, RequestContext } from "../../routes/request/index.js";
-export declare const AGENT_FIELD_NAME = "agentId";
-export type handler = (ctx: hono.Context, next: hono.Next, context: RequestContext, request?: RequestAgentRoute["implementation"], intercepts?: RequestAgentRoute["intercept"][]) => Promise<void>;
-export declare function handle(ctx: hono.Context, _next: hono.Next, context: RequestContext, request?: RequestAgentRoute["implementation"], intercepts?: RequestAgentRoute["intercept"][]): Promise<void>;
-export declare const factory: (request?: RequestAgentRoute["implementation"], intercepts?: RequestAgentRoute["intercept"][]) => handler;
+import { RequestAgentMount } from '../../routes/request/index.js';
+import { Session } from './types.js';
 /**
  * Handler utilities for agent HTTP requests.
  *
@@ -19,11 +15,7 @@ export declare const factory: (request?: RequestAgentRoute["implementation"], in
  *
  * @module server/handlers/agent
  */
-export interface Params {
-    ctx: hono.Context;
-    next: hono.Next;
-    context: Omit<RequestContext, "agentId">;
-    handler: handler;
-    user: (ctx: hono.Context) => Promise<string>;
-}
-export declare function request({ ctx, next, context, handler, user, }: Params): Promise<void>;
+export type Mount = RequestAgentMount<Session>;
+export declare const handle: Mount['handler'];
+export declare const factory: Mount['factory'];
+export declare const request: Mount['request'];

package/dist/server/hono/agent-request.js

@@ -2,23 +2,22 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import { INVALID_REQUEST } from "@artinet/sdk";
-import { RequestAgent, } from "../../routes/request/index.js";
-import * as sdk from "@artinet/sdk";
-import { handleJSONRPCResponse } from "./rpc.js";
-import { generateRequestId } from "./utils.js";
-export const AGENT_FIELD_NAME = "agentId";
-export async function handle(ctx, _next, context, request = RequestAgent, intercepts) {
+import { INVALID_REQUEST } from '@artinet/sdk';
+import { RequestAgent } from '../../routes/request/index.js';
+import * as sdk from '@artinet/sdk';
+import { handleJSONRPCResponse } from './rpc.js';
+import { generateRequestId } from './utils.js';
+import { AGENT_FIELD_NAME } from '../../default.js';
+export const handle = async ({ session: { ctx }, context, intercepts }, implementation = RequestAgent) => {
     /* hono.Context.req uses a raw JSON.parse() so we prefer to use the text() and our own safeParse() */
     const body = sdk.safeParse(await ctx.req.text());
-    const requestId = generateRequestId(context, ctx.req.header("x-request-id") ?? body?.id);
+    const requestId = generateRequestId(context, ctx.req.header('x-request-id') ?? body?.id);
     let parsed;
-    if (ctx.req.path.endsWith("agent-card.json") ||
-        ctx.req.path.endsWith("agent.json")) {
+    if (ctx.req.path.endsWith('agent-card.json') || ctx.req.path.endsWith('agent.json')) {
         parsed = {
-            jsonrpc: "2.0",
+            jsonrpc: '2.0',
             id: requestId,
-            method: "agentcard/get",
+            method: 'agentcard/get',
             params: null,
         };
     }
@@ -31,23 +30,28 @@ export async function handle(ctx, _next, context, request = RequestAgent, interc
         params: params,
     };
     sdk.logger.info(`handle agent request received:${parsed.method}:params:${sdk.formatJson(agentRequest)}`);
-    const response = await request(agentRequest, context, intercepts);
+    const response = await implementation(agentRequest, context, intercepts);
     sdk.logger.info(`handle agent request completed:${parsed.method}:response:${sdk.formatJson(response)}`);
     await handleJSONRPCResponse(ctx, requestId, parsed.method, response);
-}
-export const factory = (request = RequestAgent, intercepts) => async (ctx, next, context) => await handle(ctx, next, context, request, intercepts);
-export async function request({ ctx, next, context, handler = handle, user, }) {
+};
+export const factory = ({ implementation = RequestAgent, }) => {
+    return async (params) => {
+        return await handle(params, implementation);
+    };
+};
+export const request = async ({ session, context, handler = handle, user, intercepts }, implementation = RequestAgent) => {
+    const { ctx } = session;
     const agentId = ctx.req.param(AGENT_FIELD_NAME);
     if (!agentId) {
         throw INVALID_REQUEST({ message: `${AGENT_FIELD_NAME} is required` });
     }
-    /* hono.Context.req uses a raw JSON.parse() so we prefer to use the text() and our own safeParse() */
-    const reqId = ctx.req.header("x-request-id") ?? sdk.safeParse(await ctx.req.text())?.id;
+    /* hono.Context.req uses a raw JSON.parse() so we prefer to use text() and our own safeParse() */
+    const reqId = ctx.req.header('x-request-id') ?? sdk.safeParse(await ctx.req.text())?.id;
     const requestContext = {
         ...context,
         agentId,
         requestId: generateRequestId(context, reqId),
-        userId: await user?.(ctx),
+        userId: await user?.(session),
     };
-    await handler(ctx, next, requestContext);
-}
+    return await handler({ session, context: requestContext, intercepts }, implementation);
+};

package/dist/server/hono/deploy-request.d.ts

@@ -2,16 +2,9 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import * as hono from "hono";
-import { CreateAgentRoute } from "../../routes/create/index.js";
-export type handler = (ctx: hono.Context, next: hono.Next, context: CreateAgentRoute["context"], deploy?: CreateAgentRoute["implementation"]) => Promise<void>;
-export declare function handle(ctx: hono.Context, _next: hono.Next, context: CreateAgentRoute["context"], deploy?: CreateAgentRoute["implementation"]): Promise<void>;
-export declare const factory: (deploy?: CreateAgentRoute["implementation"]) => handler;
-export interface Params {
-    ctx: hono.Context;
-    next: hono.Next;
-    context: CreateAgentRoute["context"];
-    handler: handler;
-    user: (ctx: hono.Context) => Promise<string>;
-}
-export declare function request({ ctx, next, context, handler, user, }: Params): Promise<void>;
+import { CreateAgentMount } from '../../routes/create/index.js';
+import { Session } from './types.js';
+export type Mount = CreateAgentMount<Session>;
+export declare const factory: Mount['factory'];
+export declare const handle: Mount['handler'];
+export declare const request: Mount['request'];

package/dist/server/hono/deploy-request.js

@@ -2,26 +2,27 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import * as sdk from "@artinet/sdk";
-import { CreateAgent, CreateAgentRequestSchema, } from "../../routes/create/index.js";
-import { generateRequestId, generateRegistrationId } from "./utils.js";
-export async function handle(ctx, _next, context, deploy = CreateAgent) {
+import * as sdk from '@artinet/sdk';
+import { CreateAgent, CreateAgentRequestSchema, } from '../../routes/create/index.js';
+import { generateRequestId, generateRegistrationId } from './utils.js';
+export const factory = ({ implementation = CreateAgent }) => async (params) => await handle(params, implementation);
+export const handle = async ({ session: { ctx }, context, intercepts }, implementation = CreateAgent) => {
     /* hono.Context.req uses a raw JSON.parse() so we prefer to use the text() and our own safeParse() */
     const req = sdk.safeParse(await ctx.req.text());
     const request = await sdk.validateSchema(CreateAgentRequestSchema, req);
     sdk.logger.info(`deploying agent: ${request.config.name}`);
     sdk.logger.debug(`deploying agent: ${sdk.formatJson(request)}`);
     context.registrationId = generateRegistrationId(request.config.uri);
-    const result = await deploy(request, context);
+    const result = await implementation(request, context, intercepts);
     ctx.res = ctx.json(result);
-}
-export const factory = (deploy = CreateAgent) => async (ctx, next, context) => await handle(ctx, next, context, deploy);
-export async function request({ ctx, next, context, handler = handle, user, }) {
-    const reqId = ctx.req.header("x-request-id") ?? sdk.safeParse(await ctx.req.text())?.id;
-    const requestContext = {
+};
+export const request = async ({ session, context, handler = handle, user, intercepts }, implementation = CreateAgent) => {
+    const { ctx } = session;
+    const reqId = ctx.req.header('x-request-id') ?? sdk.safeParse(await ctx.req.text())?.id;
+    const _context = {
         ...context,
         requestId: generateRequestId(context, reqId),
-        userId: await user?.(ctx),
+        userId: await user?.(session),
     };
-    await handler(ctx, next, requestContext);
-}
+    await handler({ session, context: _context, intercepts }, implementation);
+};

package/dist/server/hono/rpc.d.ts

@@ -2,15 +2,13 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import * as hono from "hono";
-import { ResultOrError } from "../../types.js";
-export declare function toJSONRPCResponse(id: string, result_or_error: ResultOrError): {
-    jsonrpc: "2.0";
-    id: string;
-    result: unknown;
-} | {
-    jsonrpc: "2.0";
-    id: string;
-    error: unknown;
-};
+import * as hono from 'hono';
+import { ResultOrError } from '../../types.js';
+/**
+ * Handle JSON-RPC response for Hono.
+ *
+ * Used by the deployment server to provide a standard agent endpoint interface.
+ *
+ * @module server/handlers/rpc
+ */
 export declare function handleJSONRPCResponse(ctx: hono.Context, id: string, method: string, response: ResultOrError): Promise<void>;

package/dist/server/hono/rpc.js

@@ -2,48 +2,47 @@
  * Copyright 2025 The Artinet Project
  * SPDX-License-Identifier: Apache-2.0
  */
-import * as sdk from "@artinet/sdk";
-import { streamSSE } from "hono/streaming";
-export function toJSONRPCResponse(id, result_or_error) {
-    if (result_or_error.type === "success") {
-        return { jsonrpc: "2.0", id, result: result_or_error.result };
-    }
-    if (result_or_error.type === "error") {
-        return { jsonrpc: "2.0", id, error: result_or_error.error };
-    }
-    throw new Error("Invalid response type");
-}
+import * as sdk from '@artinet/sdk';
+import { streamSSE } from 'hono/streaming';
+import { toJSONRPCResponse } from '../../utils.js';
+/**
+ * Handle JSON-RPC response for Hono.
+ *
+ * Used by the deployment server to provide a standard agent endpoint interface.
+ *
+ * @module server/handlers/rpc
+ */
 export async function handleJSONRPCResponse(ctx, id, method, response) {
-    if (response.type === "success" && method === "agentcard/get") {
+    if (response.type === 'success' && method === 'agentcard/get') {
         ctx.status(200);
         ctx.res = ctx.json(response.result);
         return;
     }
-    if (response.type === "success") {
+    if (response.type === 'success') {
         ctx.status(200);
         ctx.res = ctx.json(toJSONRPCResponse(String(id), response));
         return;
     }
-    if (response.type === "error") {
+    if (response.type === 'error') {
         ctx.status(500);
         ctx.res = ctx.json(toJSONRPCResponse(String(id), response));
         return;
     }
-    if (response.type === "stream") {
+    if (response.type === 'stream') {
         const stream = response.stream;
         ctx.res = streamSSE(ctx, async (responseStream) => {
             for await (const data of stream) {
                 responseStream.writeSSE({
-                    data: JSON.stringify({ jsonrpc: "2.0", id, result: data }),
+                    data: JSON.stringify({ jsonrpc: '2.0', id, result: data }),
                 });
             }
             responseStream.close();
         });
         ctx.status(200);
-        ctx.res.headers.set("Content-Type", "text/event-stream");
-        ctx.res.headers.set("Cache-Control", "no-cache");
-        ctx.res.headers.set("Connection", "keep-alive");
+        ctx.res.headers.set('Content-Type', 'text/event-stream');
+        ctx.res.headers.set('Cache-Control', 'no-cache');
+        ctx.res.headers.set('Connection', 'keep-alive');
         return;
     }
-    throw sdk.INTERNAL_ERROR({ message: "Unknown response type" });
+    throw sdk.INTERNAL_ERROR({ message: 'Unknown response type' });
 }