@sigrun/sigrun 0.0.0-stage → 0.1.0

package/dist/server/routes/submissions.js

@@ -0,0 +1,317 @@
+/**
+ * Submission lifecycle routes: submit (content-part resolution + the §7.1
+ * async admit shape — 202 at admission, optional `waitMs`, status route),
+ * configure (model/thinking change), abort (withdraw the active
+ * submission), and compact (manual compaction).
+ * Every route resolves its conversation through the `loadConversation`
+ * pre-handler (404 for an unknown id) before touching the body.
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { UnservedModelError } from "../../harness/providers/index.js";
+import { ConversationOpError, submitOp, } from "../conversation-ops.js";
+import { loadConversation } from "../conversation-handler.js";
+import { ID_PARAMS_SCHEMA, THINKING_LEVELS, submissionId, } from "../helpers.js";
+/** Integer path params for the submission status route (§7.1). */
+const SUBMISSION_PARAMS_SCHEMA = {
+    type: "object",
+    properties: { id: { type: "integer" }, submissionId: { type: "integer" } },
+    required: ["id", "submissionId"],
+    additionalProperties: false,
+};
+/** Path params for the extension-command invoke route (W5 Task 3). */
+const COMMAND_INVOKE_PARAMS_SCHEMA = {
+    type: "object",
+    properties: { id: { type: "integer" }, name: { type: "string" } },
+    required: ["id", "name"],
+    additionalProperties: false,
+};
+/** Register the submission/configure/abort/compact routes. */
+export function registerSubmissionRoutes(app, ctx) {
+    const { opened } = ctx;
+    // Submissions: content-part resolution + upstream idempotence;
+    // `whenBusy` pass-through. The shared submit op (W5 Task 5) is the
+    // SAME code path the extension host bridge drives — content-part
+    // resolution, the served-model check, and activity stamping are
+    // identical by construction; this route owns the HTTP mapping only.
+    app.post("/v1/conversations/:id/submissions", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx, "write") }, async (request, reply) => {
+        const conversation = request.conversation;
+        const body = request.body;
+        if (body === undefined ||
+            typeof body !== "object" ||
+            Array.isArray(body)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        try {
+            const record = await submitOp(ctx, conversation, body.input, {
+                ...(body.requestId === undefined
+                    ? {}
+                    : { requestId: String(body.requestId) }),
+                ...(body.whenBusy === undefined ? {} : { whenBusy: body.whenBusy }),
+                ...(request.query?.waitMs ===
+                    undefined
+                    ? {}
+                    : {
+                        waitMs: request.query.waitMs,
+                    }),
+            });
+            return await reply.code(202).send({ submission: record });
+        }
+        catch (error) {
+            if (error instanceof ConversationOpError) {
+                return await reply.code(400).send(error.body);
+            }
+            if (error instanceof UnservedModelError) {
+                return await reply.code(400).send({
+                    error: "unserved_model",
+                    model: `${error.ref.provider}/${error.ref.modelId}`,
+                    available: error.available,
+                });
+            }
+            throw error;
+        }
+    });
+    // Submission status (§7.1): the record as it stands — the poll
+    // counterpart of the admission-202 submit. The submission must belong
+    // to THIS conversation: an unknown id and another conversation's id
+    // are the same 404 (never a cross-conversation leak).
+    app.get("/v1/conversations/:id/submissions/:submissionId", {
+        schema: { params: SUBMISSION_PARAMS_SCHEMA },
+        preHandler: loadConversation(ctx, "read"),
+    }, async (request, reply) => {
+        const conversation = request.conversation;
+        const { submissionId: rawSubmissionId } = request.params;
+        const submission = await opened.harness.submission(submissionId(rawSubmissionId), BACKGROUND_CONTEXT);
+        const record = submission === undefined
+            ? undefined
+            : await submission.status(BACKGROUND_CONTEXT);
+        if (record === undefined ||
+            record.conversationId !== conversation.id) {
+            return await reply
+                .code(404)
+                .send({ error: "submission_not_found" });
+        }
+        return { submission: record };
+    });
+    // Configure: change the conversation's model and/or thinking level.
+    // v1 accepts EXACTLY `model` + `thinking` — any other key is a fail-loud
+    // 400 (the agent's other knobs are not wire surface yet).
+    app.post("/v1/conversations/:id/configure", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx, "write") }, async (request, reply) => {
+        const conversation = request.conversation;
+        const body = request.body;
+        if (body === undefined ||
+            body === null ||
+            typeof body !== "object" ||
+            Array.isArray(body)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const unknownKey = Object.keys(body).find((key) => key !== "model" && key !== "thinking");
+        if (unknownKey !== undefined) {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: unknownKey });
+        }
+        const model = body.model;
+        const thinking = body.thinking;
+        if (model === undefined && thinking === undefined) {
+            // A configure that changes nothing is a client error, not a no-op.
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        // `model` is `"provider/modelId"`, split on the FIRST `/` (a modelId
+        // may itself contain slashes); both parts must be non-empty.
+        let parsedModel;
+        if (model !== undefined) {
+            if (typeof model !== "string" || !model.includes("/")) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: "model" });
+            }
+            const slash = model.indexOf("/");
+            const provider = model.slice(0, slash);
+            const modelId = model.slice(slash + 1);
+            if (provider.length === 0 || modelId.length === 0) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: "model" });
+            }
+            parsedModel = { provider, modelId };
+        }
+        if (thinking !== undefined &&
+            (typeof thinking !== "string" ||
+                !THINKING_LEVELS.includes(thinking))) {
+            return await reply
+                .code(400)
+                .send({ error: "invalid_field", field: "thinking" });
+        }
+        // perModelThinking: a model change re-applies the store's
+        // override for the NEW model unless the request pins `thinking` —
+        // the map is the deployment default, the explicit field the caller's
+        // win. Read from the store here, so a PATCH reaches later configures.
+        const storeThinking = parsedModel === undefined
+            ? undefined
+            : opened.settings.read().perModelThinking?.[`${parsedModel.provider}/${parsedModel.modelId}`];
+        await conversation.configure({
+            ...(parsedModel === undefined ? {} : { model: parsedModel }),
+            ...(thinking !== undefined
+                ? { thinkingLevel: thinking }
+                : storeThinking === undefined
+                    ? {}
+                    : { thinkingLevel: storeThinking }),
+        }, BACKGROUND_CONTEXT);
+        // Read the agent back and project the configured surface only —
+        // resolved extensions/tools/sections stay server-side.
+        const agent = await conversation.agent(BACKGROUND_CONTEXT);
+        return {
+            ...(agent.model === undefined ? {} : { model: agent.model }),
+            thinkingLevel: agent.thinkingLevel,
+        };
+    });
+    // Abort: withdraw/settle the conversation's active submission.
+    // `inspect()` is the read-only union of placed run inputs and queued inbox
+    // items (all conversations); filtered to this conversation, the LOWEST id
+    // is the active one — anything queued behind a busy conversation was
+    // admitted later and has a higher id.
+    app.post("/v1/conversations/:id/abort", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx, "write") }, async (request, reply) => {
+        const conversation = request.conversation;
+        const inspection = await opened.harness.inspect(BACKGROUND_CONTEXT);
+        // Lowest live id = oldest admitted = the placed run input over later-
+        // queued inbox items. reduce() with a first-element seed is ordering-
+        // independent (a future pi-durable inspect() ordering change cannot
+        // silently target the wrong submission); empty → undefined.
+        const active = inspection.submissions
+            .filter((s) => s.conversationId === conversation.id)
+            .reduce((min, s) => (min === undefined || s.id < min.id ? s : min), undefined);
+        if (active === undefined) {
+            return await reply
+                .code(404)
+                .send({ error: "no_active_submission" });
+        }
+        const result = await opened.harness.abortSubmission(active.id, BACKGROUND_CONTEXT, conversation.id);
+        // `not_found` means the submission's record vanished between `inspect`
+        // and `abort` — the conversation is no longer busy, so the honest answer
+        // is the same as nothing-active.
+        if (result === "not_found") {
+            return await reply
+                .code(404)
+                .send({ error: "no_active_submission" });
+        }
+        // `already_placed`/`settled` are still 200: abort is idempotent and
+        // the body reports which state the submission was found in.
+        return { result, submissionId: active.id };
+    });
+    // Manual compaction: `POST .../compact` (pi parity).
+    // `Conversation.compact(instructions)` (pi-durable's own manual-
+    // compaction admission, dist/harness/types.d.ts) creates a
+    // conversation-owned durable compaction task with `reason: "manual"`:
+    // it compacts even when the conversation is idle — a user's explicit
+    // intent — and places its summary through a write submission (at the
+    // next boundary when busy). Manual compaction ignores the policy's
+    // `enabled` (upstream doc: "manual compaction ignores `enabled`");
+    // `compact()` resumes the scheduler itself. The task id is handed back —
+    // the SSE stream carries the `pi.compaction` entry when the summary
+    // lands.
+    app.post("/v1/conversations/:id/compact", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx, "write") }, async (request, reply) => {
+        const conversation = request.conversation;
+        // Absent body is valid (no instructions); an object may carry
+        // ONLY `instructions` — any other key is a fail-loud 400, the
+        // configure convention.
+        const body = request.body;
+        let instructions;
+        if (body !== undefined && body !== null) {
+            if (typeof body !== "object" || Array.isArray(body)) {
+                return await reply.code(400).send({ error: "invalid_body" });
+            }
+            const record = body;
+            const unknownKey = Object.keys(record).find((key) => key !== "instructions");
+            if (unknownKey !== undefined) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: unknownKey });
+            }
+            if (record.instructions !== undefined &&
+                typeof record.instructions !== "string") {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: "instructions" });
+            }
+            instructions =
+                record.instructions === undefined || record.instructions === ""
+                    ? undefined
+                    : record.instructions;
+        }
+        const taskId = await conversation.compact(instructions, BACKGROUND_CONTEXT);
+        // 202: like submissions, the compaction is admitted, not settled —
+        // the task runs asynchronously and its summary lands as a view
+        // revision (the SSE stream).
+        return await reply.code(202).send({ taskId });
+    });
+    // Extension-command invocation (core hardening W5 Task 3, spec §9.3):
+    // `POST /v1/conversations/:id/commands/:name {args?}` runs the winning
+    // extension declaration for `name` (the merged catalog's `runnable`
+    // map — core names and dropped/collided losers resolve to 404
+    // `command_not_found`, never a run). WRITE-gated like every other
+    // conversation-mutating route (`loadConversation(ctx, "write")`: a
+    // read-only sharee gets 403). The body is at most `{args: string}`
+    // (absent body = empty args); the run ctx mirrors the ext-route
+    // adapter's — the caller's principal and the extension's seam host
+    // (`ctx.host` may be undefined for arity-0 factories, same Task 2
+    // semantics). A THROWING run is 500 `command_failed` naming the
+    // extension (logged; the server lives on); a normal return is 200
+    // with the command's optional `{notice}`.
+    app.post("/v1/conversations/:id/commands/:name", {
+        schema: { params: COMMAND_INVOKE_PARAMS_SCHEMA },
+        preHandler: loadConversation(ctx, "write"),
+    }, async (request, reply) => {
+        const conversation = request.conversation;
+        const { name } = request.params;
+        // The body convention of configure/compact: absent is valid (no
+        // args); an object may carry ONLY `args`, a non-string `args` is a
+        // fail-loud 400.
+        const body = request.body;
+        let args;
+        if (body !== undefined && body !== null) {
+            if (typeof body !== "object" || Array.isArray(body)) {
+                return await reply.code(400).send({ error: "invalid_body" });
+            }
+            const record = body;
+            const unknownKey = Object.keys(record).find((key) => key !== "args");
+            if (unknownKey !== undefined) {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: unknownKey });
+            }
+            if (record.args !== undefined && typeof record.args !== "string") {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: "args" });
+            }
+            args = record.args;
+        }
+        const merged = ctx.commandCatalog.runnable.get(name);
+        if (merged === undefined) {
+            return await reply.code(404).send({ error: "command_not_found" });
+        }
+        // The extension's seam host — the Task 2 ext-route semantics: the
+        // captured host instance, cast across the not-yet-bridged members
+        // (and possibly undefined when the loader ran without a host
+        // context factory).
+        const host = ctx.opened.seamHosts.get(merged.extension);
+        try {
+            const result = await merged.run({
+                conversationId: conversation.id,
+                args: args ?? "",
+                principal: request.principal,
+                host: host,
+            });
+            return await reply.code(200).send(result === undefined || result.notice === undefined
+                ? {}
+                : { notice: result.notice });
+        }
+        catch (cause) {
+            console.warn(`extension command failed: ${merged.extension} ${name}: ${cause instanceof Error ? cause.message : String(cause)}`);
+            return await reply.code(500).send({
+                error: "command_failed",
+                extension: merged.extension,
+            });
+        }
+    });
+}

package/dist/server/routes/users.js

@@ -0,0 +1,169 @@
+/**
+ * The users + invites routes (core hardening W1 Task 4, spec §5.8): the
+ * admin-gated directory surface — list, patch (with the last-record-admin
+ * guard: group-derived admins never count, Authelia can revoke them at
+ * any moment), delete-with-transfer (ownership rewrite → token revocation
+ * → record removal → the `userDeleted` lifecycle event), and invite
+ * issuance.
+ *
+ * The admin gate reads `request.principal.admin` — record admin, service
+ * token, the naive loopback superuser, or a proxy-group grant. The
+ * last-admin GUARDS read the directory records only (`recordAdminCount`).
+ */
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { withClaimLock } from "../auth/claim-lock.js";
+import { transferOwnership } from "../ownership.js";
+/** The wire form of one directory user (the record minus nothing — the
+ * routes serving it are admin-gated, and emails are admin material). */
+function userWire(record) {
+    return {
+        user: record.user,
+        ...(record.name === undefined ? {} : { name: record.name }),
+        ...(record.email === undefined ? {} : { email: record.email }),
+        admin: record.admin,
+        createdAt: record.createdAt,
+        source: record.source,
+    };
+}
+/** Register the users + invites routes. */
+export function registerUserRoutes(app, ctx) {
+    const { identity, eventBus } = ctx.opened;
+    app.get("/v1/users", async (request, reply) => {
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        return { users: identity.users.list().map(userWire) };
+    });
+    app.patch("/v1/users/:user", async (request, reply) => {
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        const { user } = request.params;
+        const target = identity.users.get(user);
+        if (target === undefined) {
+            return await reply.code(404).send({ error: "unknown_user" });
+        }
+        const body = request.body;
+        if (typeof body !== "object" ||
+            body === null ||
+            Array.isArray(body)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const patch = {};
+        for (const key of Object.keys(body)) {
+            const value = body[key];
+            switch (key) {
+                case "name":
+                case "email":
+                    // Absent = unchanged (clearing is not patch surface v1 —
+                    // null is a wrong type, not a clear operator, here).
+                    if (typeof value !== "string") {
+                        return await reply.code(400).send({ error: "invalid_body" });
+                    }
+                    patch[key] = value;
+                    break;
+                case "admin":
+                    if (typeof value !== "boolean") {
+                        return await reply.code(400).send({ error: "invalid_body" });
+                    }
+                    patch.admin = value;
+                    break;
+                default:
+                    return await reply
+                        .code(400)
+                        .send({ error: "invalid_field", field: key });
+            }
+        }
+        if (Object.keys(patch).length === 0) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        // The last record-admin may not demote themselves — the directory
+        // would hold no admin at all (group admins never count).
+        if (patch.admin === false &&
+            target.admin &&
+            identity.users.recordAdminCount() === 1) {
+            return await reply.code(409).send({ error: "last_admin" });
+        }
+        const updated = await identity.users.update(user, {
+            ...(patch.name === undefined ? {} : { name: patch.name }),
+            ...(patch.email === undefined ? {} : { email: patch.email }),
+            ...(patch.admin === undefined ? {} : { admin: patch.admin }),
+        });
+        return userWire(updated);
+    });
+    app.post("/v1/users/invites", async (request, reply) => {
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        const body = request.body;
+        if (typeof body !== "object" ||
+            body === null ||
+            Array.isArray(body)) {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const admin = body.admin === undefined
+            ? false
+            : body.admin;
+        if (typeof admin !== "boolean") {
+            return await reply.code(400).send({ error: "invalid_body" });
+        }
+        const expiresInMsRaw = body.expiresInMs;
+        let expiresInMs;
+        if (expiresInMsRaw !== undefined) {
+            if (typeof expiresInMsRaw !== "number" ||
+                !Number.isFinite(expiresInMsRaw) ||
+                expiresInMsRaw <= 0) {
+                return await reply.code(400).send({ error: "invalid_body" });
+            }
+            expiresInMs = expiresInMsRaw;
+        }
+        for (const key of Object.keys(body)) {
+            if (key !== "admin" && key !== "expiresInMs") {
+                return await reply
+                    .code(400)
+                    .send({ error: "invalid_field", field: key });
+            }
+        }
+        // Issuance rides the claim lock too: an invite minted while a claim
+        // is mid-flight cannot interleave with the redemption path's
+        // read-decide-write.
+        const invite = await withClaimLock(() => identity.invites.create({ admin, ...(expiresInMs === undefined ? {} : { expiresInMs }) }));
+        const response = {
+            id: invite.id,
+            code: invite.code,
+            expiresAt: invite.expiresAt,
+        };
+        return await reply.code(201).send(response);
+    });
+    app.delete("/v1/users/:user", async (request, reply) => {
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        const { user } = request.params;
+        const target = identity.users.get(user);
+        if (target === undefined) {
+            return await reply.code(404).send({ error: "unknown_user" });
+        }
+        // transferTo is required and must name ANOTHER directory user.
+        const query = request.query;
+        if (query.transferTo === undefined ||
+            query.transferTo === "" ||
+            query.transferTo === user ||
+            identity.users.get(query.transferTo) === undefined) {
+            return await reply.code(400).send({ error: "invalid_transfer" });
+        }
+        // The last record-admin may not be deleted — admin is not a
+        // transferable property (transferTo moves resources, not rights).
+        if (target.admin && identity.users.recordAdminCount() === 1) {
+            return await reply.code(409).send({ error: "last_admin" });
+        }
+        const to = query.transferTo;
+        await transferOwnership(ctx, user, to);
+        await identity.tokens.revokeAllFor(user);
+        await identity.users.remove(user);
+        // The lifecycle event: extensions transfer their own records
+        // (deadlocked-ordering free — the core transfer already landed).
+        await eventBus.emitUserDeleted({ user, transferTo: to }, BACKGROUND_CONTEXT);
+        return await reply.code(204).send();
+    });
+}