open-managed-agents 0.1.0

package/dist/src/control-plane/sessions/pi/translator.js

@@ -0,0 +1,100 @@
+export function translatePiEvent(input, context = {}) {
+    if (!isObject(input))
+        return [];
+    const type = typeof input.type === "string" ? input.type : "";
+    if (type === "agent_start") {
+        return [{ type: "session.status_running", payload: {} }];
+    }
+    if (type === "message_end") {
+        return translateMessageEnd(input, context);
+    }
+    if (type === "tool_execution_end") {
+        return translateToolExecutionEnd(input, context);
+    }
+    if (type === "agent_end") {
+        return translateAgentEnd(input);
+    }
+    return [];
+}
+function translateMessageEnd(event, context) {
+    if (!isObject(event.message))
+        return [];
+    const message = event.message;
+    const role = typeof message.role === "string" ? message.role : "";
+    if (role !== "assistant")
+        return [];
+    const drafts = [];
+    const blocks = Array.isArray(message.content) ? message.content : [];
+    const textBlocks = blocks
+        .filter(isObject)
+        .filter((b) => b.type === "text" && typeof b.text === "string")
+        .map((b) => ({ type: "text", text: b.text }));
+    if (textBlocks.length > 0) {
+        drafts.push({
+            type: "agent.message",
+            payload: { content: textBlocks },
+        });
+    }
+    for (const block of blocks) {
+        if (!isObject(block) || block.type !== "toolCall")
+            continue;
+        const toolUseId = typeof block.id === "string" ? block.id : undefined;
+        const name = typeof block.name === "string" ? block.name : undefined;
+        const args = isObject(block.arguments) ? block.arguments : {};
+        if (!toolUseId || !name)
+            continue;
+        if (context.customToolNames?.has(name))
+            continue;
+        if (context.suppressPiToolUse?.(toolUseId) === true)
+            continue;
+        // ADR 0011: event IDs stay server-assigned sevt_*; Pi's toolu_* remains
+        // payload correlation data and inbound handling translates as needed.
+        const payload = {
+            tool_use_id: toolUseId,
+            name,
+            input: args,
+        };
+        drafts.push({ type: "agent.tool_use", payload });
+    }
+    return drafts;
+}
+function translateToolExecutionEnd(event, context) {
+    const toolName = typeof event.toolName === "string" && event.toolName.length > 0
+        ? event.toolName
+        : undefined;
+    if (toolName && context.customToolNames?.has(toolName))
+        return [];
+    const toolUseId = typeof event.toolCallId === "string" && event.toolCallId.length > 0
+        ? event.toolCallId
+        : undefined;
+    if (!toolUseId)
+        return [];
+    const payload = {
+        tool_use_id: context.publicToolUseIdForPiToolCallId?.(toolUseId) ?? toolUseId,
+        content: [],
+        is_error: event.isError === true,
+    };
+    if (isObject(event.result)) {
+        if (Array.isArray(event.result.content)) {
+            payload.content = event.result.content;
+        }
+    }
+    return [{ type: "agent.tool_result", payload }];
+}
+function translateAgentEnd(event) {
+    // Provisional mapping: C.0 fixtures only observed willRetry=false.
+    // Keep this branch explicit (and easy to delete) until a retry trajectory
+    // is captured and the event shape is confirmed in fixtures.
+    if (event.willRetry === true) {
+        return [{ type: "session.status_rescheduled", payload: {} }];
+    }
+    return [
+        {
+            type: "session.status_idle",
+            payload: { stop_reason: { type: "end_turn" } },
+        },
+    ];
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/src/control-plane/sessions/request.js

@@ -0,0 +1,164 @@
+import { isJsonObject } from "../../types/json.js";
+import { invalidRequest } from "../errors.js";
+const MAX_SESSION_VAULT_IDS = 20;
+export function parseCreateSession(input) {
+    const obj = objectInput(input);
+    rejectUnsupportedField(obj, "sandbox");
+    rejectUnsupportedField(obj, "sandbox_provider");
+    rejectUnsupportedField(obj, "sandboxProviderSelection");
+    rejectUnsupportedField(obj, "sandboxProviderSelectionOptions");
+    rejectUnsupportedField(obj, "sandboxProviderFactory");
+    rejectUnknownFields(obj, [
+        "agent",
+        "environment_id",
+        "vault_ids",
+        "title",
+        "metadata",
+        "resources",
+    ]);
+    return {
+        agent: agentField(obj),
+        environment_id: stringField(obj, "environment_id", { required: true }),
+        vault_ids: vaultIdsField(obj),
+        title: nullableStringField(obj, "title") ?? undefined,
+        metadata: metadataField(obj) ?? undefined,
+        resources: resourcesField(obj),
+    };
+}
+function vaultIdsField(obj) {
+    const value = obj.vault_ids;
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw invalidRequest("`vault_ids` must be an array of vault ids");
+    }
+    if (value.length > MAX_SESSION_VAULT_IDS) {
+        throw invalidRequest(`\`vault_ids\` must contain at most ${MAX_SESSION_VAULT_IDS} vaults`);
+    }
+    return value.map((item) => {
+        if (typeof item !== "string" || !item.startsWith("vlt_")) {
+            throw invalidRequest("`vault_ids` entries must be vault ids");
+        }
+        return item;
+    });
+}
+export function parseAgentRef(agent) {
+    if (typeof agent === "string")
+        return { id: agent };
+    return agent.version === undefined
+        ? { id: agent.id }
+        : { id: agent.id, version: agent.version };
+}
+function rejectUnsupportedField(obj, field) {
+    if (obj[field] !== undefined) {
+        throw invalidRequest(`Field \`${field}\` is not yet supported by this server.`);
+    }
+}
+function rejectUnknownFields(obj, allowedFields) {
+    const allowed = new Set(allowedFields);
+    for (const field of Object.keys(obj)) {
+        if (allowed.has(field))
+            continue;
+        throw invalidRequest(`Unsupported session create field: \`${field}\`.`);
+    }
+}
+function objectInput(input) {
+    if (!isJsonObject(input)) {
+        throw invalidRequest("Request body must be a JSON object");
+    }
+    return input;
+}
+function agentField(obj) {
+    const value = obj.agent;
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (isJsonObject(value)) {
+        const type = stringField(value, "type", { required: true });
+        if (type !== "agent") {
+            throw invalidRequest("`agent.type` must be `agent`");
+        }
+        const version = value.version;
+        if (version !== undefined) {
+            if (typeof version !== "number" ||
+                !Number.isSafeInteger(version) ||
+                version <= 0) {
+                throw invalidRequest("`agent.version` must be a positive integer");
+            }
+            return {
+                type,
+                id: stringField(value, "id", { required: true }),
+                version,
+            };
+        }
+        return {
+            type,
+            id: stringField(value, "id", { required: true }),
+        };
+    }
+    throw invalidRequest("`agent` must be a non-empty string or agent object");
+}
+function stringField(obj, field, opts = {}) {
+    const value = obj[field];
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (value === undefined && opts.required !== true)
+        return "";
+    throw invalidRequest(`\`${field}\` must be a non-empty string`);
+}
+function nullableStringField(obj, field) {
+    const value = obj[field];
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (typeof value === "string")
+        return value;
+    throw invalidRequest(`\`${field}\` must be a string or null`);
+}
+function metadataField(obj) {
+    const value = obj.metadata;
+    if (value === undefined)
+        return undefined;
+    if (!isJsonObject(value)) {
+        throw invalidRequest("`metadata` must be an object");
+    }
+    const metadata = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (typeof v !== "string") {
+            throw invalidRequest("`metadata` values must be strings");
+        }
+        metadata[k] = v;
+    }
+    return metadata;
+}
+function resourcesField(obj) {
+    const value = obj.resources;
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value)) {
+        throw invalidRequest("`resources` must be an array");
+    }
+    return value.map((entry, index) => resourceField(entry, index));
+}
+function resourceField(value, index) {
+    if (!isJsonObject(value)) {
+        throw invalidRequest(`\`resources[${index}]\` must be an object`);
+    }
+    const type = stringField(value, "type", { required: true });
+    if (type !== "file") {
+        throw invalidRequest(`Unsupported session resource type: ${type}.`);
+    }
+    rejectUnknownFields(value, ["type", "file_id", "mount_path"]);
+    const mountPath = nullableStringField(value, "mount_path");
+    return {
+        type,
+        file_id: resourceStringField(value, "file_id", index),
+        ...(mountPath === undefined || mountPath === null ? {} : { mount_path: mountPath }),
+    };
+}
+function resourceStringField(obj, field, index) {
+    const value = obj[field];
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    throw invalidRequest(`\`resources[${index}].${field}\` must be a non-empty string`);
+}

package/dist/src/control-plane/sessions/resources.js

@@ -0,0 +1,63 @@
+import { invalidRequest } from "../errors.js";
+const SESSION_UPLOADS_ROOT = "/mnt/session/uploads";
+const SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
+const MAX_SEGMENT_LENGTH = 255;
+const MAX_CANONICAL_MOUNT_PATH_LENGTH = 1024;
+export function normalizeSessionMountPath(mountPath, fileId) {
+    const raw = mountPath ?? fileId;
+    if (raw.includes("\0")) {
+        throw invalidRequest("Invalid file resource: mount_path must not contain NUL bytes");
+    }
+    if (raw.includes("\\")) {
+        throw invalidRequest("Invalid file resource: mount_path must not contain backslashes");
+    }
+    const relative = raw.replace(/^\/+/, "");
+    if (relative.length === 0) {
+        throw invalidRequest("Invalid file resource: mount_path must not be empty");
+    }
+    const segments = relative.split("/");
+    for (const segment of segments) {
+        validateSegment(segment);
+    }
+    const canonical = `${SESSION_UPLOADS_ROOT}/${segments.join("/")}`;
+    if (canonical.length > MAX_CANONICAL_MOUNT_PATH_LENGTH) {
+        throw invalidRequest("Invalid file resource: mount_path exceeds 1024 characters");
+    }
+    return { mountPath: canonical, segments };
+}
+export function normalizeSessionFileResources(resources) {
+    const normalized = resources.map((resource) => ({
+        fileId: resource.fileId,
+        ...normalizeSessionMountPath(resource.mountPath, resource.fileId),
+    }));
+    for (let i = 0; i < normalized.length; i += 1) {
+        for (let j = i + 1; j < normalized.length; j += 1) {
+            const left = normalized[i];
+            const right = normalized[j];
+            if (left.mountPath === right.mountPath) {
+                throw invalidRequest("Duplicate file resource mount_path");
+            }
+            if (isPrefix(left.segments, right.segments) || isPrefix(right.segments, left.segments)) {
+                throw invalidRequest("Overlapping file resource mount_path");
+            }
+        }
+    }
+    return normalized;
+}
+function validateSegment(segment) {
+    if (segment.length === 0) {
+        throw invalidRequest("Invalid file resource: mount_path segment must not be empty");
+    }
+    if (segment === "." || segment === "..") {
+        throw invalidRequest("Invalid file resource: mount_path must not contain . or .. segments");
+    }
+    if (segment.length > MAX_SEGMENT_LENGTH) {
+        throw invalidRequest("Invalid file resource: mount_path segment exceeds 255 characters");
+    }
+    if (!SEGMENT_PATTERN.test(segment)) {
+        throw invalidRequest("Invalid file resource: mount_path contains unsupported characters");
+    }
+}
+function isPrefix(left, right) {
+    return left.length < right.length && left.every((segment, index) => segment === right[index]);
+}

package/dist/src/control-plane/sessions/routes.js

@@ -0,0 +1,88 @@
+import { Hono } from "hono";
+import { parseJsonBody, parseLimit, parseOrder } from "../http.js";
+import { invalidRequest } from "../errors.js";
+import { requestFingerprint, validateIdempotencyKey, } from "../request-idempotency.js";
+import { workspaceIdFrom } from "../workspace.js";
+import { toManagedSession } from "./serialize.js";
+export function sessionsRoutes(service, events) {
+    const app = new Hono();
+    app.post("/", async (c) => {
+        const idempotencyKey = c.req.header("idempotency-key");
+        if (idempotencyKey !== undefined) {
+            const rawBody = new Uint8Array(await c.req.raw.arrayBuffer());
+            const body = parseJsonBytes(rawBody);
+            const method = c.req.method.toUpperCase();
+            const concretePath = new URL(c.req.url).pathname;
+            const response = await service.createIdempotent(workspaceIdFrom(c), body, {
+                method,
+                concretePath,
+                key: validateIdempotencyKey(idempotencyKey),
+                routeLabel: "POST /v1/sessions",
+                fingerprintSha256: requestFingerprint(method, concretePath, rawBody),
+            }, { requestId: c.get("requestId") });
+            return jsonResponse(response.body, response.status, c.get("requestId"), response.headers);
+        }
+        const body = await parseJsonBody(c.req);
+        const session = await service.create(workspaceIdFrom(c), body);
+        return c.json(session, 200);
+    });
+    app.get("/", (c) => {
+        const limit = parseLimit(c.req.query("limit"));
+        const page = c.req.query("page") || undefined;
+        const order = parseOrder(c.req.query("order"));
+        const agentId = c.req.query("agent_id") || undefined;
+        const includeArchived = parseBoolean(c.req.query("include_archived"));
+        return c.json(service.list(workspaceIdFrom(c), {
+            ...(limit === undefined ? {} : { limit }),
+            ...(page === undefined ? {} : { page }),
+            ...(order === undefined ? {} : { order }),
+            ...(agentId === undefined ? {} : { agentId }),
+            ...(includeArchived === undefined ? {} : { includeArchived }),
+        }), 200);
+    });
+    app.get("/:id", (c) => {
+        return c.json(service.retrieve(workspaceIdFrom(c), c.req.param("id")), 200);
+    });
+    app.post("/:id/archive", async (c) => {
+        const sessionId = c.req.param("id");
+        const row = events.archiveSessionRowAfterPreflight(workspaceIdFrom(c), sessionId);
+        await events.archiveSession(workspaceIdFrom(c), sessionId);
+        return c.json(toManagedSession(row), 200);
+    });
+    app.delete("/:id", async (c) => {
+        const sessionId = c.req.param("id");
+        // The running-session guard lives in service.delete (domain-owned), so it
+        // runs before any mutation regardless of caller; the route stays thin.
+        const deleted = await service.delete(workspaceIdFrom(c), sessionId);
+        await events.deleteSession(workspaceIdFrom(c), sessionId);
+        return c.json(deleted, 200);
+    });
+    return app;
+}
+function parseJsonBytes(bytes) {
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch (error) {
+        throw invalidRequest("Request body must be valid JSON", String(error));
+    }
+}
+function jsonResponse(body, status, requestId, extraHeaders = {}) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            "content-type": "application/json",
+            "request-id": requestId,
+            ...extraHeaders,
+        },
+    });
+}
+function parseBoolean(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    throw invalidRequest("`include_archived` must be `true` or `false`");
+}

package/dist/src/control-plane/sessions/serialize.js

@@ -0,0 +1,24 @@
+export function toManagedSession(row) {
+    return {
+        id: row.id,
+        type: row.type,
+        agent: row.agent,
+        environment_id: row.environment_id,
+        vault_ids: [...(row.vault_ids ?? [])],
+        status: row.status,
+        title: row.title,
+        metadata: row.metadata,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        archived_at: row.archived_at,
+        usage: row.usage,
+        resources: row.resources.map((resource) => ({
+            id: resource.id,
+            type: resource.type,
+            file_id: resource.file_id,
+            mount_path: resource.mount_path,
+            created_at: resource.created_at,
+            updated_at: resource.updated_at,
+        })),
+    };
+}