@hexis-ai/engram-server 0.12.0 → 0.14.0

package/dist/routes/orgs.js

@@ -0,0 +1,185 @@
+/**
+ * Cookie-auth org self-service routes (Wave G5).
+ *
+ * Auth gating only — the underlying logic lives in services/orgs.ts so
+ * the admin-token surface (`/admin/v1/orgs/*`) can call the same code
+ * without duplicating it.
+ *
+ * Mount BEFORE the workspace gate in src/server.ts; these endpoints
+ * have their own membership check and a chosen workspace would be
+ * irrelevant noise.
+ */
+import { Hono } from "hono";
+import { addMember, createWorkspaceUnderOrg, OrgServiceError, removeMember, revokeWorkspaceKey, updateOrg, updateOrgWorkspace, } from "../services/orgs";
+const WRITE_ROLES = new Set(["owner", "admin"]);
+export function orgsRoutes(opts) {
+    const app = new Hono();
+    const deps = { orgStore: opts.orgStore, keyStore: opts.keyStore };
+    const requireMember = async (req, orgId, minRole = "member") => {
+        const s = await opts.authHandler.api
+            .getSession({ headers: req.headers })
+            .catch(() => null);
+        if (!s?.user)
+            return jsonResponse(401, "unauthorized");
+        const memberships = await opts.orgStore.listOrgsForUser(s.user.id);
+        const here = memberships.find((m) => m.orgId === orgId);
+        if (!here)
+            return jsonResponse(403, "forbidden");
+        if (minRole !== "member" && !WRITE_ROLES.has(here.role)) {
+            return jsonResponse(403, "forbidden");
+        }
+        return { user: { id: s.user.id }, role: here.role };
+    };
+    // ---------- org ---------------------------------------------
+    app.get("/v1/orgs/:id", async (c) => {
+        const gate = await requireMember(c.req.raw, c.req.param("id"));
+        if (gate instanceof Response)
+            return gate;
+        const org = await opts.orgStore.getOrg(c.req.param("id"));
+        if (!org)
+            return c.json({ error: "org_not_found" }, 404);
+        return c.json({ org, role: gate.role });
+    });
+    app.patch("/v1/orgs/:id", async (c) => {
+        const id = c.req.param("id");
+        const gate = await requireMember(c.req.raw, id, "admin");
+        if (gate instanceof Response)
+            return gate;
+        return runService(c, async () => {
+            const body = (await c.req.json().catch(() => ({})));
+            const org = await updateOrg(deps, id, body);
+            return c.json({ org });
+        });
+    });
+    // ---------- members -----------------------------------------
+    app.get("/v1/orgs/:id/members", async (c) => {
+        const gate = await requireMember(c.req.raw, c.req.param("id"));
+        if (gate instanceof Response)
+            return gate;
+        return c.json({ members: await opts.orgStore.listMembers(c.req.param("id")) });
+    });
+    app.post("/v1/orgs/:id/members", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        return runService(c, async () => {
+            const body = (await c.req.json().catch(() => ({})));
+            const member = await addMember(deps, orgId, body);
+            return c.json({ member });
+        });
+    });
+    app.delete("/v1/orgs/:id/members/:userId", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        return runService(c, async () => {
+            await removeMember(deps, orgId, c.req.param("userId"));
+            return c.body(null, 204);
+        });
+    });
+    // ---------- workspaces -------------------------------------
+    app.get("/v1/orgs/:id/workspaces", async (c) => {
+        const gate = await requireMember(c.req.raw, c.req.param("id"));
+        if (gate instanceof Response)
+            return gate;
+        const workspaces = await opts.orgStore.listWorkspacesForOrg(c.req.param("id"));
+        return c.json({ workspaces });
+    });
+    app.patch("/v1/orgs/:id/workspaces/:wsId", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        const wsId = c.req.param("wsId");
+        const ok = await opts.orgStore.userCanAccessWorkspace(gate.user.id, wsId);
+        if (!ok)
+            return c.json({ error: "workspace_not_in_org" }, 404);
+        return runService(c, async () => {
+            const body = (await c.req.json().catch(() => ({})));
+            return c.json(await updateOrgWorkspace(deps, orgId, wsId, body));
+        });
+    });
+    app.delete("/v1/orgs/:id/workspaces/:wsId", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        const wsId = c.req.param("wsId");
+        const ok = await opts.orgStore.userCanAccessWorkspace(gate.user.id, wsId);
+        if (!ok)
+            return c.json({ error: "workspace_not_in_org" }, 404);
+        await opts.keyStore.deleteWorkspace(wsId);
+        return c.body(null, 204);
+    });
+    app.post("/v1/orgs/:id/workspaces", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        return runService(c, async () => {
+            const body = (await c.req.json().catch(() => ({})));
+            return c.json(await createWorkspaceUnderOrg(deps, orgId, body));
+        });
+    });
+    // ---------- api keys (scoped to a workspace) ----------------
+    app.get("/v1/orgs/:id/workspaces/:wsId/keys", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        const wsId = c.req.param("wsId");
+        const ok = await opts.orgStore.userCanAccessWorkspace(gate.user.id, wsId);
+        if (!ok)
+            return c.json({ error: "workspace_not_in_org" }, 404);
+        return c.json({ keys: await opts.keyStore.listKeys(wsId) });
+    });
+    app.post("/v1/orgs/:id/workspaces/:wsId/keys", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        const wsId = c.req.param("wsId");
+        const ok = await opts.orgStore.userCanAccessWorkspace(gate.user.id, wsId);
+        if (!ok)
+            return c.json({ error: "workspace_not_in_org" }, 404);
+        const body = (await c.req.json().catch(() => ({})));
+        const key = await opts.keyStore.issueKey(wsId, {
+            ...(body.name !== undefined ? { name: body.name } : {}),
+        });
+        return c.json(key);
+    });
+    app.delete("/v1/orgs/:id/workspaces/:wsId/keys/:keyId", async (c) => {
+        const orgId = c.req.param("id");
+        const gate = await requireMember(c.req.raw, orgId, "admin");
+        if (gate instanceof Response)
+            return gate;
+        const wsId = c.req.param("wsId");
+        const ok = await opts.orgStore.userCanAccessWorkspace(gate.user.id, wsId);
+        if (!ok)
+            return c.json({ error: "workspace_not_in_org" }, 404);
+        return runService(c, async () => {
+            await revokeWorkspaceKey(deps, wsId, c.req.param("keyId"));
+            return c.body(null, 204);
+        });
+    });
+    return app;
+}
+function jsonResponse(status, error) {
+    return new Response(JSON.stringify({ error }), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+/** Run a service call, mapping OrgServiceError to a JSON response. */
+async function runService(c, fn) {
+    try {
+        return await fn();
+    }
+    catch (e) {
+        if (e instanceof OrgServiceError)
+            return c.json({ error: e.code }, e.status);
+        throw e;
+    }
+}

package/dist/schemas.d.ts

@@ -24,6 +24,8 @@ export declare const sessionInitSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     trigger_conversation_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     trigger_event_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    trigger_purpose: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    trigger_resume_hint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export declare const sessionUpdateSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -37,6 +39,8 @@ export declare const sessionUpdateSchema: z.ZodObject<{
     model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     trigger_conversation_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     trigger_event_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    trigger_purpose: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    trigger_resume_hint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export declare const sessionEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"step">;
@@ -161,6 +165,24 @@ export declare const createWorkspaceSchema: z.ZodObject<{
 export declare const issueKeySchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const createOrgSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const orgPatchSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const workspacePatchSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const addMemberSchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /**
  * Read and validate a JSON request body. Returns the parsed value, or a
  * `Response` (400) the caller should return as-is:

package/dist/schemas.js

@@ -20,6 +20,8 @@ export const sessionInitSchema = z.object({
     model: z.string().nullable().optional(),
     trigger_conversation_id: z.string().nullable().optional(),
     trigger_event_id: z.string().nullable().optional(),
+    trigger_purpose: z.string().nullable().optional(),
+    trigger_resume_hint: z.string().nullable().optional(),
 });
 export const sessionUpdateSchema = z.object({
     title: z.string().nullable().optional(),
@@ -29,6 +31,8 @@ export const sessionUpdateSchema = z.object({
     model: z.string().nullable().optional(),
     trigger_conversation_id: z.string().nullable().optional(),
     trigger_event_id: z.string().nullable().optional(),
+    trigger_purpose: z.string().nullable().optional(),
+    trigger_resume_hint: z.string().nullable().optional(),
 });
 const stepEventSchema = z.object({
     type: z.literal("step"),
@@ -151,6 +155,25 @@ export const createWorkspaceSchema = z.object({
 export const issueKeySchema = z.object({
     name: z.string().optional(),
 });
+// --- Orgs (admin + self-serve share these bodies) --------------------
+export const createOrgSchema = z.object({
+    id: z.string().optional(),
+    name: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const orgPatchSchema = z.object({
+    name: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const workspacePatchSchema = z.object({
+    name: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const addMemberSchema = z.object({
+    userId: z.string().optional(),
+    email: z.string().optional(),
+    role: z.string().optional(),
+});
 // --- Helper ----------------------------------------------------------
 /**
  * Read and validate a JSON request body. Returns the parsed value, or a

package/dist/server.d.ts

@@ -4,6 +4,7 @@ import type { CookieAuthResolver } from "./auth-resolver";
 import type { AuthResolver, Env } from "./context";
 import type { OrgStore } from "./org-store";
 import { type AdminOptions } from "./admin";
+import type { KeyStore } from "./key-store";
 export interface CreateServerOptions {
     /** Resolves Bearer / X-Api-Key tokens into workspace contexts. */
     auth: AuthResolver;
@@ -22,8 +23,20 @@ export interface CreateServerOptions {
      * Optional: org store. When provided AND \`authHandler\` is set,
      * exposes \`GET /v1/me/workspaces\` and \`GET /v1/me/orgs\` so
      * engram-web can populate its org / workspace switcher.
+     *
+     * Combined with \`keyStore\` it also unlocks the cookie-auth
+     * \`/v1/orgs/:id/*\` self-service surface (members, workspaces,
+     * api keys) — see routes/orgs.ts.
      */
     orgStore?: OrgStore;
+    /**
+     * Optional: key store, shared between the admin router and the
+     * cookie-auth orgs surface. The admin router takes its own
+     * reference (\`admin.keyStore\`) for the legacy / api-key flows;
+     * this top-level handle lets \`/v1/orgs/:id/*\` issue and revoke
+     * workspace keys without the admin token.
+     */
+    keyStore?: KeyStore;
     /**
      * Generates session ids. Defaults to `crypto.randomUUID()`.
      * Provide a custom function for deterministic ids in tests.

package/dist/server.js

@@ -7,6 +7,8 @@ import { sessionsRoutes } from "./routes/sessions";
 import { personsRoutes } from "./routes/persons";
 import { identitiesRoutes } from "./routes/identities";
 import { searchRoutes } from "./routes/search";
+import { orgsRoutes } from "./routes/orgs";
+import { buildOpenApiDocument } from "./openapi";
 /**
  * Build the engram HTTP app. Wiring only: this sets up cross-cutting
  * middleware (request id + access log), the workspace auth gate, and mounts
@@ -91,6 +93,10 @@ export function createServer(opts) {
         },
     }));
     app.get("/healthz", (c) => c.json({ ok: true }));
+    // OpenAPI 3.1 document for the public /v1 surface. Served live
+    // from the same Zod schemas the server validates with, so it
+    // can't drift. engram-web's /docs renders this through Scalar.
+    app.get("/openapi.json", (c) => c.json(buildOpenApiDocument()));
     if (opts.admin) {
         app.route("/admin/v1", createAdminRouter(opts.admin));
     }
@@ -100,33 +106,15 @@ export function createServer(opts) {
         const handler = opts.authHandler;
         app.all("/auth/*", (c) => handler.handler(c.req.raw));
     }
-    // Workspace auth gate — every `/v1/*` route runs behind this. Tries
-    // api-key first; falls back to cookie session when configured. The
-    // Bearer header is reserved for api-keys here; engram-web uses the
-    // session cookie, not a Bearer.
-    app.use("/v1/*", async (c, next) => {
-        const apiKey = c.req.header("x-api-key") ??
-            c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
-        let ctx = apiKey ? await opts.auth(apiKey) : null;
-        if (!ctx && !apiKey && opts.cookieAuth) {
-            ctx = await opts.cookieAuth(c.req.raw);
-        }
-        if (!ctx)
-            return c.json({ error: "unauthorized" }, 401);
-        c.set("ctx", ctx);
-        await next();
-    });
-    // Identity probe — echoes the workspace the caller's auth
-    // resolves to. Cheap, used as a health/whoami by clients.
-    app.get("/v1/me", (c) => c.json({ workspaceId: c.var.ctx.workspaceId }));
     // Cookie-auth helpers for engram-web: list every workspace / org
-    // the signed-in user can reach. api-key callers don't need these
-    // (they already know which workspace they're scoped to).
+    // the signed-in user can reach. Mounted BEFORE the workspace gate
+    // because these endpoints are how the UI chooses a workspace —
+    // gating them on x-workspace-id would deadlock new sign-ins.
     if (opts.authHandler && opts.orgStore) {
-        const auth = opts.authHandler;
+        const handler = opts.authHandler;
         const orgStore = opts.orgStore;
         const requireUser = async (req) => {
-            const s = await auth.api.getSession({ headers: req.headers }).catch(() => null);
+            const s = await handler.api.getSession({ headers: req.headers }).catch(() => null);
             return s?.user ?? null;
         };
         app.get("/v1/me/workspaces", async (c) => {
@@ -147,7 +135,36 @@ export function createServer(opts) {
             })));
             return c.json({ orgs: orgs.filter((o) => o.id) });
         });
+        // Org self-service surface (Wave G5): members, workspaces, api
+        // keys — same shape as the admin endpoints but cookie-auth +
+        // org-membership + role check.
+        if (opts.keyStore) {
+            app.route("/", orgsRoutes({
+                authHandler: handler,
+                orgStore,
+                keyStore: opts.keyStore,
+            }));
+        }
     }
+    // Workspace auth gate — every other `/v1/*` route runs behind this.
+    // Tries api-key first; falls back to cookie session when configured.
+    // The Bearer header is reserved for api-keys here; engram-web uses
+    // the session cookie, not a Bearer.
+    app.use("/v1/*", async (c, next) => {
+        const apiKey = c.req.header("x-api-key") ??
+            c.req.header("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
+        let ctx = apiKey ? await opts.auth(apiKey) : null;
+        if (!ctx && !apiKey && opts.cookieAuth) {
+            ctx = await opts.cookieAuth(c.req.raw);
+        }
+        if (!ctx)
+            return c.json({ error: "unauthorized" }, 401);
+        c.set("ctx", ctx);
+        await next();
+    });
+    // Identity probe — echoes the workspace the caller's auth
+    // resolves to. Cheap, used as a health/whoami by clients.
+    app.get("/v1/me", (c) => c.json({ workspaceId: c.var.ctx.workspaceId }));
     app.route("/v1", sessionsRoutes(cfg));
     app.route("/v1", personsRoutes(cfg));
     app.route("/v1", identitiesRoutes(cfg));

package/dist/services/orgs.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Org / workspace business logic shared between the admin-token surface
+ * (`/admin/v1/*`) and the cookie-auth self-service surface (`/v1/orgs/*`).
+ *
+ * Auth and HTTP framing stay in the route modules. This file owns:
+ *   - the multi-step orchestrations (createWorkspaceUnderOrg writes
+ *     the workspace + org binding atomically and then issues a key;
+ *     email→userId lookup + upsertMember)
+ *   - the safety invariants (workspace id validation, last-owner
+ *     protection on member removal)
+ *   - the canonical error → status mapping (OrgServiceError.status)
+ *
+ * Functions throw {@link OrgServiceError} for caller errors; route
+ * handlers catch it and translate to JSON. Storage errors that aren't
+ * known caller faults propagate.
+ */
+import { type IssuedKey, type KeyStore, type Workspace } from "../key-store";
+import type { OrgMembershipRow, OrgRow, OrgStore } from "../org-store";
+export type OrgServiceErrorStatus = 400 | 403 | 404;
+/** Caller-fault errors with a stable code → status mapping. */
+export declare class OrgServiceError extends Error {
+    readonly code: string;
+    readonly status: OrgServiceErrorStatus;
+    constructor(code: string, status: OrgServiceErrorStatus);
+}
+export interface OrgServiceDeps {
+    orgStore: OrgStore;
+    keyStore: KeyStore;
+}
+export declare function getOrgOrThrow(deps: OrgServiceDeps, id: string): Promise<OrgRow>;
+export declare function createOrg(deps: OrgServiceDeps, body: {
+    id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<OrgRow>;
+export declare function updateOrg(deps: OrgServiceDeps, id: string, body: {
+    name?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<OrgRow>;
+export declare function deleteOrg(deps: OrgServiceDeps, id: string): Promise<void>;
+export interface AddMemberInput {
+    userId?: string;
+    email?: string;
+    role?: string;
+}
+/**
+ * Resolve an email or explicit userId to a membership row, upserting at
+ * the requested role. Used by both the admin and self-serve surfaces.
+ */
+export declare function addMember(deps: OrgServiceDeps, orgId: string, input: AddMemberInput): Promise<OrgMembershipRow>;
+/**
+ * Remove a membership. Refuses to remove the org's sole remaining owner
+ * (would brick the org). Applies to admin-token callers too —
+ * `deleteOrg` is the path for tearing down an org entirely.
+ */
+export declare function removeMember(deps: OrgServiceDeps, orgId: string, userId: string): Promise<void>;
+export interface CreateWorkspaceInput {
+    id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    /** Whether to issue an initial API key. Default true. */
+    issueKey?: boolean;
+    /** Optional name applied to the initial API key. */
+    keyName?: string;
+}
+export interface CreateWorkspaceResult {
+    workspace: Workspace & {
+        orgId: string;
+    };
+    /** Present unless `issueKey === false`. */
+    key?: IssuedKey;
+}
+/**
+ * Stand up a new workspace under an org. The workspace + org binding
+ * commit atomically because the KeyStore writes `org_id` in the same
+ * INSERT as the workspace row. Issuing the initial API key remains a
+ * follow-up call (idempotent — a retry of the workspace POST returns
+ * the existing row via ON CONFLICT DO NOTHING).
+ *
+ * Validates the workspace id shape up front so a bad id fails before
+ * touching the store. Returns the workspace with `orgId` stamped on so
+ * callers don't need a second lookup.
+ */
+export declare function createWorkspaceUnderOrg(deps: OrgServiceDeps, orgId: string, body: CreateWorkspaceInput): Promise<CreateWorkspaceResult>;
+export declare function updateOrgWorkspace(deps: OrgServiceDeps, orgId: string, wsId: string, body: {
+    name?: string;
+    metadata?: Record<string, unknown>;
+}): Promise<{
+    workspace: Workspace & {
+        orgId: string;
+    };
+}>;
+export declare function revokeWorkspaceKey(deps: OrgServiceDeps, wsId: string, keyId: string): Promise<void>;
+/**
+ * Throw `workspace_not_in_org` (404) if the workspace's `org_id` is
+ * not `orgId`. Used by both the admin-token and cookie-auth surfaces
+ * to scope per-workspace operations to the URL's org.
+ */
+export declare function requireWorkspaceInOrg(deps: OrgServiceDeps, orgId: string, wsId: string): Promise<void>;

package/dist/services/orgs.js

@@ -0,0 +1,163 @@
+/**
+ * Org / workspace business logic shared between the admin-token surface
+ * (`/admin/v1/*`) and the cookie-auth self-service surface (`/v1/orgs/*`).
+ *
+ * Auth and HTTP framing stay in the route modules. This file owns:
+ *   - the multi-step orchestrations (createWorkspaceUnderOrg writes
+ *     the workspace + org binding atomically and then issues a key;
+ *     email→userId lookup + upsertMember)
+ *   - the safety invariants (workspace id validation, last-owner
+ *     protection on member removal)
+ *   - the canonical error → status mapping (OrgServiceError.status)
+ *
+ * Functions throw {@link OrgServiceError} for caller errors; route
+ * handlers catch it and translate to JSON. Storage errors that aren't
+ * known caller faults propagate.
+ */
+import { isValidWorkspaceId, } from "../key-store";
+/** Caller-fault errors with a stable code → status mapping. */
+export class OrgServiceError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(code);
+        this.code = code;
+        this.status = status;
+    }
+}
+// ---------- orgs ---------------------------------------------------
+export async function getOrgOrThrow(deps, id) {
+    const org = await deps.orgStore.getOrg(id);
+    if (!org)
+        throw new OrgServiceError("org_not_found", 404);
+    return org;
+}
+export async function createOrg(deps, body) {
+    try {
+        return await deps.orgStore.createOrg({
+            ...(body.id !== undefined ? { id: body.id } : {}),
+            ...(body.name !== undefined ? { name: body.name } : {}),
+            ...(body.metadata !== undefined ? { metadata: body.metadata } : {}),
+        });
+    }
+    catch (e) {
+        throw new OrgServiceError(e.message, 400);
+    }
+}
+export async function updateOrg(deps, id, body) {
+    try {
+        return await deps.orgStore.updateOrg(id, body);
+    }
+    catch (e) {
+        if (e.message === "org_not_found") {
+            throw new OrgServiceError("org_not_found", 404);
+        }
+        throw e;
+    }
+}
+export async function deleteOrg(deps, id) {
+    await getOrgOrThrow(deps, id);
+    await deps.orgStore.deleteOrg(id);
+}
+/**
+ * Resolve an email or explicit userId to a membership row, upserting at
+ * the requested role. Used by both the admin and self-serve surfaces.
+ */
+export async function addMember(deps, orgId, input) {
+    let userId = input.userId;
+    if (!userId && input.email) {
+        const u = await deps.orgStore.findUserByEmail(input.email);
+        if (!u)
+            throw new OrgServiceError("user_not_found", 404);
+        userId = u.id;
+    }
+    if (!userId)
+        throw new OrgServiceError("userId_or_email_required", 400);
+    return await deps.orgStore.upsertMember({
+        orgId,
+        userId,
+        ...(input.role !== undefined ? { role: input.role } : {}),
+    });
+}
+/**
+ * Remove a membership. Refuses to remove the org's sole remaining owner
+ * (would brick the org). Applies to admin-token callers too —
+ * `deleteOrg` is the path for tearing down an org entirely.
+ */
+export async function removeMember(deps, orgId, userId) {
+    const members = await deps.orgStore.listMembers(orgId);
+    const owners = members.filter((m) => m.role === "owner");
+    if (owners.length === 1 && owners[0].userId === userId) {
+        throw new OrgServiceError("cannot_remove_last_owner", 400);
+    }
+    await deps.orgStore.removeMember(orgId, userId);
+}
+/**
+ * Stand up a new workspace under an org. The workspace + org binding
+ * commit atomically because the KeyStore writes `org_id` in the same
+ * INSERT as the workspace row. Issuing the initial API key remains a
+ * follow-up call (idempotent — a retry of the workspace POST returns
+ * the existing row via ON CONFLICT DO NOTHING).
+ *
+ * Validates the workspace id shape up front so a bad id fails before
+ * touching the store. Returns the workspace with `orgId` stamped on so
+ * callers don't need a second lookup.
+ */
+export async function createWorkspaceUnderOrg(deps, orgId, body) {
+    if (body.id !== undefined && !isValidWorkspaceId(body.id)) {
+        throw new OrgServiceError("invalid_workspace_id", 400);
+    }
+    try {
+        const ws = await deps.keyStore.createWorkspace({
+            ...(body.id !== undefined ? { id: body.id } : {}),
+            ...(body.name !== undefined ? { name: body.name } : {}),
+            ...(body.metadata !== undefined ? { metadata: body.metadata } : {}),
+            orgId,
+        });
+        if (body.issueKey === false) {
+            return { workspace: { ...ws, orgId } };
+        }
+        const key = await deps.keyStore.issueKey(ws.id, {
+            ...(body.keyName !== undefined ? { name: body.keyName } : {}),
+        });
+        return { workspace: { ...ws, orgId }, key };
+    }
+    catch (e) {
+        if (e instanceof OrgServiceError)
+            throw e;
+        throw new OrgServiceError(e.message, 400);
+    }
+}
+export async function updateOrgWorkspace(deps, orgId, wsId, body) {
+    try {
+        const ws = await deps.keyStore.updateWorkspace(wsId, body);
+        return { workspace: { ...ws, orgId } };
+    }
+    catch (e) {
+        if (e.message === "workspace_not_found") {
+            throw new OrgServiceError("workspace_not_found", 404);
+        }
+        throw e;
+    }
+}
+export async function revokeWorkspaceKey(deps, wsId, keyId) {
+    try {
+        await deps.keyStore.revokeKey(wsId, keyId);
+    }
+    catch (e) {
+        if (e.message === "key_not_found") {
+            throw new OrgServiceError("key_not_found", 404);
+        }
+        throw e;
+    }
+}
+/**
+ * Throw `workspace_not_in_org` (404) if the workspace's `org_id` is
+ * not `orgId`. Used by both the admin-token and cookie-auth surfaces
+ * to scope per-workspace operations to the URL's org.
+ */
+export async function requireWorkspaceInOrg(deps, orgId, wsId) {
+    if (!(await deps.orgStore.workspaceInOrg(orgId, wsId))) {
+        throw new OrgServiceError("workspace_not_in_org", 404);
+    }
+}

package/dist/storage.d.ts

@@ -147,5 +147,13 @@ export interface SessionRow {
     model?: string;
     trigger_conversation_id?: string;
     trigger_event_id?: string;
+    trigger_purpose?: string;
+    trigger_resume_hint?: string;
 }
 export declare function foldEvents(row: SessionRow, events: SessionEvent[], now: Date): Session;
+/**
+ * Allocate a fresh person id (`p_` + 8 alphanumeric chars). Cryptographically
+ * random via `crypto.getRandomValues`; shared between every adapter so id
+ * shape and entropy stay aligned.
+ */
+export declare function newPersonId(): string;