@cavi-ai/api-client 0.1.0

package/docs/cavi-team-manifest.example.ts

@@ -0,0 +1,219 @@
+// Consumer/plugin-owned CAVI team manifest example.
+// Keep this in the gateway/plugin config layer, then send it to mobile/web as
+// runtime configuration. Do not move these entries into package defaults.
+import {
+  normalizeTeamManifest,
+  type TeamManifest,
+  type TeamRegistryConfig,
+} from "@cavi-ai/api-client";
+
+export const CAVI_TEAM_MANIFEST = {
+  version: 1,
+  actions: [
+    {
+      id: "status-report",
+      input: {
+        mode: "json",
+        params: [{ key: "window", type: "string", default: "today" }],
+      },
+      output: { mode: "markdown", contentType: "text/markdown" },
+      capabilities: ["status.read"],
+    },
+  ],
+  teams: [
+    {
+      id: "control-plane",
+      identity: {
+        displayName: "Control Plane",
+        slug: "control-plane",
+        code: "CTRL",
+        portalId: "operator",
+        aliases: ["ops-control"],
+      },
+      workspace: {
+        rootPath: "/teams/control-plane/workspace-control-plane",
+        paths: [
+          "ops/status",
+          { key: "dispatch.templates", path: "dispatch/spawn-templates" },
+        ],
+      },
+      actions: [
+        {
+          id: "operator-snapshot",
+          input: { mode: "json" },
+          output: { mode: "json", contentType: "application/json" },
+          capabilities: ["operator.snapshot"],
+        },
+      ],
+      members: [
+        {
+          id: "operator-team",
+          capabilities: ["operator.read", "operator.write"],
+        },
+      ],
+    },
+    {
+      id: "research",
+      identity: {
+        displayName: "Research",
+        slug: "research",
+        code: "RND",
+        portalId: "scout",
+        aliases: ["scout-school"],
+      },
+      workspace: {
+        rootPath: "/teams/research/workspace-research",
+        paths: [
+          "research/complete",
+          { key: "media.images", path: "media/images" },
+          { key: "state.public", path: "state/public" },
+        ],
+      },
+      actions: [
+        {
+          id: "summarize",
+          input: {
+            mode: "json",
+            params: [{ key: "documentId", type: "string", required: true }],
+          },
+          output: { mode: "json", contentType: "application/json" },
+          capabilities: ["research.complete"],
+        },
+      ],
+      members: [
+        {
+          id: "research-operator",
+          capabilities: ["research.complete", "media.images"],
+          actions: [{ id: "summarize", defaults: { lane: "research-operator" } }],
+        },
+      ],
+    },
+    {
+      id: "project-ops",
+      identity: {
+        displayName: "Project Ops",
+        slug: "project-ops",
+        code: "PROJ",
+        portalId: "deb",
+        aliases: ["project-board"],
+      },
+      workspace: {
+        rootPath: "/teams/project-ops/workspace-project-ops",
+        paths: [
+          { key: "board.backlog", path: "project-board/backlog" },
+          { key: "board.sprint", path: "project-board/sprint" },
+        ],
+      },
+      actions: [
+        {
+          id: "sync-backlog",
+          input: {
+            mode: "json",
+            params: [{ key: "sprintId", type: "string" }],
+          },
+          output: { mode: "json", contentType: "application/json" },
+          capabilities: ["project-board.write"],
+        },
+      ],
+      members: [
+        {
+          id: "project-board",
+          capabilities: ["project-board.read", "project-board.write"],
+        },
+      ],
+    },
+    {
+      id: "machine",
+      identity: {
+        displayName: "Machine",
+        slug: "machine",
+        code: "MCH",
+        portalId: "machine",
+        aliases: ["comedy-room"],
+      },
+      workspace: {
+        rootPath: "/teams/machine/workspace-machine",
+        paths: [
+          { key: "media.images", path: "media/images" },
+          { key: "media.audio", path: "media/audio" },
+        ],
+      },
+      actions: [
+        {
+          id: "render-meme",
+          input: { mode: "json" },
+          output: {
+            mode: "artifact",
+            artifacts: [{ key: "image", contentType: "image/png" }],
+          },
+          capabilities: ["media.image.generate"],
+        },
+        {
+          id: "speak",
+          input: { mode: "text" },
+          output: { mode: "artifact", contentType: "audio/mpeg" },
+          capabilities: ["media.audio.generate"],
+        },
+      ],
+      members: [
+        {
+          id: "comedy-room",
+          capabilities: ["media.image.generate", "media.audio.generate"],
+        },
+      ],
+    },
+  ],
+  bindings: [
+    {
+      id: "research-chat",
+      teamId: "research",
+      memberId: "research-operator",
+      source: "chat",
+      sessionKeyPattern: "agent:{memberId}:*",
+      routeKey: "agent.config",
+    },
+    {
+      id: "project-board-sync",
+      teamId: "project-ops",
+      memberId: "project-board",
+      source: "portal",
+      channel: "deb",
+      actionId: "sync-backlog",
+    },
+    {
+      id: "operator-runs",
+      teamId: "control-plane",
+      source: "operator",
+      routeKey: "runs",
+    },
+  ],
+} satisfies TeamManifest;
+
+export function createCaviTeamRegistryConfig(): TeamRegistryConfig {
+  return {
+    provider: "openclaw",
+    manifest: normalizeTeamManifest(CAVI_TEAM_MANIFEST),
+    libraries: {
+      fleet: {
+        scope: "fleet",
+        libraryTeamId: "cavi-fleet-library",
+        ownerPortalId: "operator",
+        lookupKeys: ["fleet-library", "control-plane-library"],
+      },
+      teams: [
+        {
+          scope: "team",
+          libraryTeamId: "research-library",
+          ownerPortalId: "scout",
+          lookupKeys: ["research-docs", "scout-school"],
+        },
+        {
+          scope: "team",
+          libraryTeamId: "project-ops-library",
+          ownerPortalId: "deb",
+          lookupKeys: ["project-board-docs"],
+        },
+      ],
+    },
+  };
+}

package/docs/team-manifest.consumer.template.ts

@@ -0,0 +1,248 @@
+// Consumer-owned example for team/member/action registry edits.
+// Shared HTTP, runtime, envelope, media, wiki, and transport behavior belongs
+// to @cavi-ai/api-client core/provider modules, not to manifest entries.
+import {
+  normalizeTeamManifest,
+  type TeamActionContract,
+  type TeamManifest,
+  type TeamManifestMember,
+  type TeamManifestTeam,
+  type TeamRegistryConfig,
+} from "@cavi-ai/api-client";
+
+export const TEAM_MANIFEST = {
+  version: 1,
+  teams: [
+    {
+      id: "default",
+      identity: {
+        displayName: "Default Team",
+        slug: "default",
+        code: "DEFAULT",
+      },
+      workspace: {
+        rootPath: "/teams/default/workspace",
+        paths: [
+          "config",
+          "kanban",
+          "runs",
+          { key: "media.images", path: "media/images" },
+          { key: "research.complete", path: "research/complete" },
+        ],
+      },
+      actions: [
+        {
+          id: "summarize",
+          input: {
+            mode: "json",
+            params: [{ key: "documentId", type: "string", required: true }],
+          },
+          output: { mode: "json", contentType: "application/json" },
+        },
+      ],
+      members: [
+        {
+          id: "default-agent",
+          capabilities: ["kanban.read", "runs.read", "config.read"],
+          actions: [
+            {
+              id: "summarize",
+              defaults: { tone: "brief" },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+  bindings: [
+    {
+      id: "default-web",
+      teamId: "default",
+      memberId: "default-agent",
+      source: "web",
+      sessionKeyPattern: "agent:{memberId}:*",
+      routeKey: "agent.config",
+    },
+  ],
+} satisfies TeamManifest;
+
+export function addAgentToManifest(
+  manifest: TeamManifest,
+  teamId: string,
+  agent: TeamManifestMember,
+): TeamManifest {
+  const normalized = normalizeTeamManifest(manifest);
+  const teams = normalized.teams.map((team) => {
+    if (team.id !== teamId) {
+      return team;
+    }
+    return upsertMember(team, agent);
+  });
+
+  if (!teams.some((team) => team.id === teamId)) {
+    teams.push({
+      id: teamId,
+      identity: {
+        displayName: teamId,
+        slug: teamId,
+        code: teamId,
+      },
+      members: [agent],
+    });
+  }
+
+  return normalizeTeamManifest({
+    version: normalized.version,
+    actions: normalized.actions,
+    bindings: normalized.bindings,
+    teams,
+  });
+}
+
+export function removeAgentFromManifest(
+  manifest: TeamManifest,
+  teamId: string,
+  agentId: string,
+): TeamManifest {
+  const normalized = normalizeTeamManifest(manifest);
+  return normalizeTeamManifest({
+    version: normalized.version,
+    actions: normalized.actions,
+    bindings: normalized.bindings,
+    teams: normalized.teams.map((team) => {
+      if (team.id !== teamId) {
+        return team;
+      }
+      return {
+        ...team,
+        members: team.members?.filter((member) => member.id !== agentId) ?? [],
+      };
+    }),
+  });
+}
+
+export function upsertTeamAction(
+  manifest: TeamManifest,
+  teamId: string,
+  action: TeamActionContract,
+): TeamManifest {
+  const normalized = normalizeTeamManifest(manifest);
+  return normalizeTeamManifest({
+    version: normalized.version,
+    actions: normalized.actions,
+    bindings: normalized.bindings,
+    teams: normalized.teams.map((team) =>
+      team.id === teamId ? upsertActionOnTeam(team, action) : team,
+    ),
+  });
+}
+
+export function upsertAgentActionOverride(
+  manifest: TeamManifest,
+  teamId: string,
+  agentId: string,
+  action: TeamActionContract,
+): TeamManifest {
+  const normalized = normalizeTeamManifest(manifest);
+  return normalizeTeamManifest({
+    version: normalized.version,
+    actions: normalized.actions,
+    bindings: normalized.bindings,
+    teams: normalized.teams.map((team) => {
+      if (team.id !== teamId) {
+        return team;
+      }
+      return {
+        ...team,
+        members: (team.members ?? []).map((member) =>
+          member.id === agentId ? upsertActionOnMember(member, action) : member,
+        ),
+      };
+    }),
+  });
+}
+
+export function removeAgentActionOverride(
+  manifest: TeamManifest,
+  teamId: string,
+  agentId: string,
+  actionId: string,
+): TeamManifest {
+  const normalized = normalizeTeamManifest(manifest);
+  return normalizeTeamManifest({
+    version: normalized.version,
+    actions: normalized.actions,
+    bindings: normalized.bindings,
+    teams: normalized.teams.map((team) => {
+      if (team.id !== teamId) {
+        return team;
+      }
+      return {
+        ...team,
+        members: (team.members ?? []).map((member) =>
+          member.id === agentId
+            ? {
+                ...member,
+                actions: (member.actions ?? []).filter(
+                  (action) => action.id !== actionId,
+                ),
+              }
+            : member,
+        ),
+      };
+    }),
+  });
+}
+
+export function createRegistryConfig(
+  manifest: TeamManifest = TEAM_MANIFEST,
+): TeamRegistryConfig {
+  return {
+    provider: "gateway",
+    manifest: normalizeTeamManifest(manifest),
+  };
+}
+
+function upsertMember(
+  team: TeamManifestTeam,
+  agent: TeamManifestMember,
+): TeamManifestTeam {
+  const members = team.members ?? [];
+  const nextMembers = members.some((member) => member.id === agent.id)
+    ? members.map((member) => (member.id === agent.id ? agent : member))
+    : [...members, agent];
+  return {
+    ...team,
+    members: nextMembers,
+  };
+}
+
+function upsertActionOnTeam(
+  team: TeamManifestTeam,
+  action: TeamActionContract,
+): TeamManifestTeam {
+  return {
+    ...team,
+    actions: upsertAction(team.actions, action),
+  };
+}
+
+function upsertActionOnMember(
+  member: TeamManifestMember,
+  action: TeamActionContract,
+): TeamManifestMember {
+  return {
+    ...member,
+    actions: upsertAction(member.actions, action),
+  };
+}
+
+function upsertAction(
+  actions: readonly TeamActionContract[] | null | undefined,
+  action: TeamActionContract,
+): TeamActionContract[] {
+  const current = actions ?? [];
+  return current.some((entry) => entry.id === action.id)
+    ? current.map((entry) => (entry.id === action.id ? action : entry))
+    : [...current, action];
+}

package/docs/team-manifest.md

@@ -0,0 +1,252 @@
+# Team Manifest Contract
+
+The team manifest is the preferred consumer-owned shape for frontend team and
+agent registry config. The package owns the contract, normalization, path
+grammar, and guardrails; the consuming app owns the actual team entries.
+
+## Goals
+
+- Keep the default case small: a team can have one member and still satisfy the
+  registry contract.
+- Avoid one route per product/team. Shared routes are generated from team and
+  member identity.
+- Keep product-specific folders as controlled customizations by whitelisting
+  relative workspace paths.
+- Keep local workspace roots out of HTTP paths. API paths use only team/member
+  identity plus the whitelisted relative workspace path.
+
+## Boundary Status
+
+The manifest remains consumer-owned configuration. Shared HTTP, runtime,
+gateway envelope, media, wiki, SSE, and WebSocket behavior lives in core and
+provider modules; manifest entries should describe teams, members, workspace
+whitelists, capabilities, and action overrides only. Do not add transport
+behavior, product runtime globals, or local filesystem assumptions to a team
+entry.
+
+The generic manifest contract intentionally lives in `src/contracts` because
+`team.*` routes are gateway-agnostic. CAVI/operator registry behavior stays in
+`src/extensions/cavi/registry`; apps can use the manifest without inheriting a
+CAVI registry layout.
+
+## Shape
+
+```ts
+import type { TeamManifest } from "@cavi-ai/api-client";
+
+export const TEAM_MANIFEST = {
+  version: 1,
+  teams: [
+    {
+      id: "research",
+      identity: {
+        displayName: "Research",
+        slug: "research",
+        code: "RND",
+        aliases: ["scout-school"],
+      },
+      workspace: {
+        rootPath: "/teams/research/workspace-research",
+        paths: [
+          "research/complete",
+          { key: "media.images", path: "media/images" },
+        ],
+      },
+      actions: [
+        {
+          id: "summarize",
+          input: {
+            mode: "json",
+            params: [{ key: "documentId", type: "string", required: true }],
+          },
+          output: { mode: "json", contentType: "application/json" },
+        },
+      ],
+      members: [
+        {
+          id: "scout",
+          capabilities: ["research.complete"],
+        },
+      ],
+    },
+  ],
+  bindings: [
+    {
+      id: "research-chat",
+      teamId: "research",
+      memberId: "scout",
+      source: "chat",
+      sessionKeyPattern: "agent:{memberId}:*",
+      routeKey: "agent.config",
+    },
+  ],
+} satisfies TeamManifest;
+```
+
+## Generated Routes
+
+Common routes are generated from identity:
+
+```ts
+resolvePath("team.kanban", "canonical", { teamId: "research" });
+// /api/teams/research/kanban
+
+resolvePath("team.runs", "canonical", { teamId: "research" });
+// /api/teams/research/runs
+
+resolvePath("team.config", "canonical", { teamId: "research" });
+// /api/teams/research/config
+
+resolvePath("team.agent.config", "canonical", {
+  teamId: "research",
+  agentId: "scout",
+});
+// /api/teams/research/agents/scout/config
+```
+
+Workspace API routes are also generated, but callers should use the manifest
+resolver so the path is checked against the whitelist:
+
+```ts
+const manifest = normalizeTeamManifest(TEAM_MANIFEST);
+const team = findTeamManifestTeam(manifest, "research");
+
+if (!team) throw new Error("missing team");
+
+resolveTeamWorkspaceApiPath(team, "media.images", { memberId: "scout" });
+// /api/teams/research/agents/scout/workspace/media/images
+
+resolveTeamWorkspacePath(team, "media.images", { memberId: "scout" });
+// /teams/research/workspace-research/media/images
+```
+
+`resolveTeamWorkspacePath` returns a local workspace path for trusted consumer
+code. `resolveTeamWorkspaceApiPath` returns the HTTP path and never includes the
+workspace root.
+
+Team/member/action IDs are single URL path segments, so slashes, backslashes,
+query/hash characters, and dot segments are rejected instead of encoded.
+Workspace roots must be absolute path roots, and workspace entries must be
+relative allowlist entries with no traversal or encoded separators.
+
+## Gateway Route Bindings
+
+Bindings connect runtime sources to manifest-owned teams, members, and actions
+without adding package-level routes for every chat app, room, or deployment.
+The consumer owns binding entries; this package normalizes them and resolves the
+final route through the same team route grammar.
+
+```ts
+const binding = resolveGatewayRouteBinding(manifest, {
+  source: "chat",
+  key: "agent:scout:main",
+  agentId: "scout",
+});
+
+binding?.path;
+// /api/teams/research/agents/scout/config
+```
+
+`sessionKeyPattern` supports `*` wildcards plus `{teamId}`, `{memberId}`, and
+`{actionId}` placeholders. If no explicit `routeKey` is supplied, action
+bindings resolve to team or member action routes, and non-action bindings
+resolve to the team runs route.
+
+## Action Overrides
+
+Actions are the generic escape hatch for agent-specific behavior. Define the
+shared action contract once at the manifest or team level, then let a team or
+member override the last details.
+
+```ts
+const manifest = normalizeTeamManifest({
+  version: 1,
+  actions: [
+    {
+      id: "joke",
+      input: {
+        mode: "command",
+        command: "/joke",
+        params: [
+          { key: "topic", type: "string", required: true },
+          { key: "dark", type: "boolean", default: false },
+        ],
+      },
+      output: { mode: "markdown", contentType: "text/markdown" },
+      defaults: { long: false },
+    },
+  ],
+  teams: [
+    {
+      id: "machine",
+      actions: [{ id: "joke", defaults: { long: true } }],
+      members: [
+        {
+          id: "chris",
+          actions: [
+            {
+              id: "joke",
+              output: { mode: "json", contentType: "application/json" },
+              defaults: { dark: true, style: "degen" },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+});
+
+const action = resolveTeamActionContract(manifest, "machine", "joke", {
+  memberId: "chris",
+});
+
+resolveTeamActionApiPath(manifest, "machine", "joke", { memberId: "chris" });
+// /api/teams/machine/agents/chris/actions/joke
+```
+
+The merge order is:
+
+1. Manifest action defaults.
+2. Team action overrides.
+3. Member action overrides.
+4. Request-time params owned by the consumer or gateway.
+
+Command strings such as `/joke --dark --long "topic"` should be treated as UI
+sugar. Consumers should normalize them to the resolved action id plus params
+before sending the request. Responses should use the stable `TeamActionResponse`
+union (`json`, `text`, `markdown`, or `artifact`) instead of inventing a custom
+body shape for each agent.
+
+## Add Or Remove Agents
+
+Keep add/remove logic in the consumer. A registry editor should mutate the
+consumer manifest, then pass the normalized manifest into this package:
+
+```ts
+configureTeamRegistryConfig({
+  provider: "gateway",
+  manifest: normalizeTeamManifest(TEAM_MANIFEST),
+});
+```
+
+Use [team-manifest.consumer.template.ts](team-manifest.consumer.template.ts)
+as the reference shape for consumer-side add/remove helpers.
+Use [cavi-team-manifest.example.ts](cavi-team-manifest.example.ts) as the
+CAVI plugin-owned starter manifest for control-plane, research, project-ops,
+and machine portals.
+
+## Extension Path Ownership
+
+The generic manifest contract stays in `src/contracts/**` because `team.*`
+routes are gateway-agnostic. CAVI plugin routes stay in
+`src/extensions/cavi/contracts/**`; they should append to extension-owned base
+paths with helpers such as `appendCaviApiPath`, `resolvePortalApiPath`, or
+`resolveLibraryApiPath` instead of adding product-specific route grammar to
+core contracts.
+
+## Path Policy
+
+CAVI, Project Board, Martina, Machine, Front Door, and portal-memory paths stay
+inside the CAVI extension. New team-shaped frontend surfaces should prefer the
+agnostic `team.*` contracts and manifest workspace whitelist rather than adding
+another product-specific path literal.