@orchestraworks/cli 0.5.5 → 0.5.8

package/dist/constructs/references.d.ts

@@ -43,6 +43,10 @@ export interface ImageBuildProps {
     /** `docker build --platform`; omitted when unset so the invocation is unchanged. */
     platform?: string;
 }
+/** A built tag with no registry path is uploaded to the platform rather than pushed to a registry. */
+export declare function isHostedImageTag(tag: string): boolean;
+/** The image name a hosted tag uploads under: the part before `:`. */
+export declare function hostedImageName(tag: string): string;
 export declare class Image {
     private constructor();
     /** No plan import — the tag rides the environment payload. */

package/dist/constructs/references.js

@@ -209,6 +209,18 @@ export function parseEnvImportMarker(v) {
 }
 /** The platform's `environments.image` column cap. */
 const MAX_IMAGE_TAG_LENGTH = 512;
+/** The platform's `POST /images` name rule: ECR's repository grammar, here without a path. */
+const HOSTED_IMAGE_NAME = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
+const MAX_HOSTED_IMAGE_NAME_LENGTH = 128;
+/** A built tag with no registry path is uploaded to the platform rather than pushed to a registry. */
+export function isHostedImageTag(tag) {
+    return !tag.includes("/");
+}
+/** The image name a hosted tag uploads under: the part before `:`. */
+export function hostedImageName(tag) {
+    const colon = tag.indexOf(":");
+    return colon === -1 ? tag : tag.slice(0, colon);
+}
 export class Image {
     constructor() {
         // static-only
@@ -235,6 +247,14 @@ export class Image {
             throw new Error(`Image.fromBuild tag exceeds the platform's ${MAX_IMAGE_TAG_LENGTH}-character image limit ` +
                 `(${props.tag.length} characters).`);
         }
+        if (isHostedImageTag(props.tag)) {
+            const name = hostedImageName(props.tag);
+            if (name.length > MAX_HOSTED_IMAGE_NAME_LENGTH || !HOSTED_IMAGE_NAME.test(name)) {
+                throw new Error(`Image.fromBuild tag '${props.tag}' has no registry path, so apply uploads it as the image '${name}'. ` +
+                    `That name must be 1 to ${MAX_HOSTED_IMAGE_NAME_LENGTH} characters of lowercase letters and digits, ` +
+                    `with single '.', '_' or '-' characters only between them.`);
+            }
+        }
         const factory = Factory._current();
         if (factory === undefined) {
             throw new Error("Image.fromBuild requires an active Factory: construct new Factory({...}) first.");

package/dist/constructs/role.d.ts

@@ -0,0 +1,32 @@
+import { Construct } from "../core/construct.js";
+import type { PlanResource } from "../core/plan.js";
+import type { IPolicy, IRole } from "./interfaces.js";
+/** The managed roles, by slug; a managed role's slug is its id. */
+export declare const MANAGED_ROLE_SLUGS: readonly ["role_managed_owner", "role_managed_admin", "role_managed_developer", "role_managed_factory_user", "role_managed_agent_worker", "role_managed_agent_manager", "role_managed_compute_launcher"];
+export type ManagedRoleSlug = (typeof MANAGED_ROLE_SLUGS)[number];
+/** Owner is assignable at all teams only: at one team it would be that team's Admin and nothing more. */
+export declare const OWNER_ROLE_SLUG: ManagedRoleSlug;
+export interface RoleProps {
+    name: string;
+    description?: string;
+    labels?: Record<string, string>;
+    policies: readonly IPolicy[];
+}
+export declare class Role extends Construct implements IRole {
+    readonly roleId: string;
+    private readonly name;
+    private readonly description;
+    private readonly labels;
+    private readonly policyIds;
+    constructor(scope: Construct, id: string, props: RoleProps);
+    /** @internal */
+    _resourceId(): string;
+    _toPlanResource(): PlanResource;
+    /** Checked at runtime as well, because an app runs transpiled and untypechecked. */
+    static managed(slug: ManagedRoleSlug): IRole;
+}
+export declare class Policy {
+    private constructor();
+    /** Apply checks that the policy exists before it writes anything. */
+    static fromId(scope: Construct, id: string): IPolicy;
+}

package/dist/constructs/role.js

@@ -0,0 +1,77 @@
+// A role carries no scope: a team membership row places it at one team or at all teams. The platform derives
+// a custom role's slug from its name, so the name is the key apply finds a live custom role by.
+import { Construct } from "../core/construct.js";
+import { validateDeclaredLabels } from "../core/labels.js";
+import { refToken } from "../core/tokens.js";
+import { registerImport } from "./references.js";
+/** The managed roles, by slug; a managed role's slug is its id. */
+export const MANAGED_ROLE_SLUGS = [
+    "role_managed_owner",
+    "role_managed_admin",
+    "role_managed_developer",
+    "role_managed_factory_user",
+    "role_managed_agent_worker",
+    "role_managed_agent_manager",
+    "role_managed_compute_launcher",
+];
+/** Owner is assignable at all teams only: at one team it would be that team's Admin and nothing more. */
+export const OWNER_ROLE_SLUG = "role_managed_owner";
+/** A platform id: a lowercase prefix word, `_`, then a suffix; a managed policy's suffix holds `_` too. */
+const POLICY_ID_PATTERN = /^[a-z][a-z0-9]*_[A-Za-z0-9_]*[A-Za-z0-9]$/;
+export class Role extends Construct {
+    roleId;
+    name;
+    description;
+    labels;
+    policyIds;
+    constructor(scope, id, props) {
+        super(scope, id);
+        const label = `role '${this.node.path.join("/")}'`;
+        if (typeof props.name !== "string" || props.name.trim() === "") {
+            throw new Error(`${label}: declare a name. A custom role's name is its key in the organization.`);
+        }
+        validateDeclaredLabels(props.labels, `${label} labels`);
+        this.name = props.name;
+        this.description = props.description;
+        this.labels = props.labels !== undefined ? { ...props.labels } : undefined;
+        // Sorted, because the order a role lists its policies in has no meaning and must not read as drift.
+        this.policyIds = [...new Set(props.policies.map((policy) => policy.policyId))].sort();
+        this.roleId = refToken("role", this.node.path);
+    }
+    /** @internal */
+    _resourceId() {
+        return this.roleId;
+    }
+    _toPlanResource() {
+        const payload = {
+            name: this.name,
+            ...(this.description !== undefined ? { description: this.description } : {}),
+            ...(this.labels !== undefined ? { labels: { ...this.labels } } : {}),
+            policyIds: [...this.policyIds],
+        };
+        return { kind: "role", path: this.node.path.join("/"), slug: this.name, managed: true, payload };
+    }
+    /** Checked at runtime as well, because an app runs transpiled and untypechecked. */
+    static managed(slug) {
+        if (!MANAGED_ROLE_SLUGS.includes(slug)) {
+            throw new Error(`'${String(slug)}' names no managed role. Use one of ${JSON.stringify(MANAGED_ROLE_SLUGS)}, or declare ` +
+                `a custom role with new Role(scope, id, { name, policies }).`);
+        }
+        return { roleId: slug, _resourceId: () => slug };
+    }
+}
+export class Policy {
+    constructor() {
+        // static-only
+    }
+    /** Apply checks that the policy exists before it writes anything. */
+    static fromId(scope, id) {
+        if (!POLICY_ID_PATTERN.test(id)) {
+            throw new Error(`Invalid policy id ${JSON.stringify(id)} for Policy.fromId: a policy has no slug, so name it by its ` +
+                `platform id, a lowercase prefix word, '_', then the rest of the id (e.g. 'pol_01jq…' or ` +
+                `'pol_managed_agent_shared_use').`);
+        }
+        registerImport(scope, { kind: "policy", ref: id }, id);
+        return { policyId: id, _resourceId: () => id };
+    }
+}

package/dist/constructs/rules.d.ts

@@ -23,21 +23,21 @@ export type RuleWhen = ConditionWhen | ChangedWhen | ActivityWhen;
 export type ResourceRef = string | {
     readonly slug: string;
 };
-/** Who an `assign` hands the item to: an agent, pinned to a version or not, a user, or a group. */
+/** Who an `assign` hands the item to: an agent, pinned to a version or not, a user, or a team. */
 export type AssignTarget = {
     readonly agent: ResourceRef;
     readonly agentVersion?: number;
 } | {
     readonly user: string;
 } | {
-    readonly group: ResourceRef;
+    readonly team: ResourceRef;
 };
 /** The `assign` action's body, which a `createWorkItem` also takes; at most one assignee is set. */
 export interface AssignBody {
     readonly assigneeAgent?: string;
     readonly agentVersion?: number;
     readonly assigneeUser?: string;
-    readonly assigneeGroup?: string;
+    readonly assigneeTeam?: string;
 }
 export type MessageTarget = {
     readonly agent: string;
@@ -134,7 +134,7 @@ export declare function changed(field: string): ChangedWhen;
 /** Every feed entry of the kind; an `INBOUND_EVENT` may name one outside event type. */
 export declare function activity(kind: WorkItemActivityKind, type?: string): ActivityWhen;
 /**
- * An agent, pinned to a version or not, a user, or a group, which hands the item on as its `assignment` says;
+ * An agent, pinned to a version or not, a user, or a team, which hands the item on as its `assignment` says;
  * see {@link unassign} for clearing it.
  */
 export declare function assign(target: AssignTarget): RuleAction;

package/dist/constructs/rules.js

@@ -56,7 +56,7 @@ export function activity(kind, type) {
     return type === undefined ? { activity: kind } : { activity: kind, type };
 }
 /**
- * An agent, pinned to a version or not, a user, or a group, which hands the item on as its `assignment` says;
+ * An agent, pinned to a version or not, a user, or a team, which hands the item on as its `assignment` says;
  * see {@link unassign} for clearing it.
  */
 export function assign(target) {
@@ -144,8 +144,8 @@ export function createWorkItem(item) {
 function assignBody(target) {
     if ("user" in target)
         return { assigneeUser: target.user };
-    if ("group" in target)
-        return { assigneeGroup: refOf(target.group) };
+    if ("team" in target)
+        return { assigneeTeam: refOf(target.team) };
     return {
         assigneeAgent: refOf(target.agent),
         ...(target.agentVersion !== undefined ? { agentVersion: target.agentVersion } : {}),

package/dist/constructs/secret.d.ts

@@ -1,7 +1,7 @@
 import type { InjectionRecipe } from "@orchestraworks/client";
 import { Construct } from "../core/construct.js";
 import type { PlanResource, ValueFrom } from "../core/plan.js";
-import type { CredentialBindingData, IGatewayKey, ISecret } from "./interfaces.js";
+import type { CredentialBindingData, IGatewayKey, ISecret, ITeam } from "./interfaces.js";
 /**
  * The request mutations the broker applies from this secret: `headers` are injected after credential
  * rendering, `removeHeaders` strips client-sent headers before injection. `removeHeaders` is optional here
@@ -65,8 +65,36 @@ export declare class SecretValue {
     static registryCredential(username: string, password: SecretValue): SecretValue;
     /** Both parts are credential material; the derived value is built only at apply. */
     static ecrCredential(accessKeyId: SecretValue, secretAccessKey: SecretValue): SecretValue;
+    /**
+     * One secret whose value is a JSON object of named fields, for credentials one request needs together: its
+     * `injection` recipe presents each field as `${secret.<name>}`, so the two headers ride one secret instead
+     * of two secrets that would both cover the host. Each field keeps its own source, so an operator keeps one
+     * environment variable per value; the object is composed only at apply, and only when every field resolves.
+     */
+    static fields(fields: Record<string, SecretValue>): SecretValue;
     _toValueFrom(): ValueFrom;
 }
+/**
+ * A credential's `hosts` use the egress rule host syntax — an exact host, `*.` and a suffix, or `*`, with no
+ * port — and a pattern the platform refuses at write is refused here.
+ */
+export declare function normalizeCredentialHosts(hosts: string[], label: string): string[];
+export interface SecretProps {
+    value: SecretValue;
+    slug?: string;
+    name?: string;
+    description?: string;
+    injection?: InjectionRecipeProps;
+    /**
+     * The hosts this secret is presented on, in egress rule host syntax: an exact host, `*.suffix`, or `*`. A
+     * request to a covered host gets the `injection` headers at the egress edge; an environment's rules only
+     * decide whether the request may leave. Omitted, the secret covers no host, and apply sends `[]`, so
+     * removing the prop clears the list.
+     */
+    hosts?: string[];
+    /** Fixed at create; undeclared, the secret is created in Shared. */
+    team?: ITeam;
+}
 export declare class Secret extends Construct implements ISecret {
     #private;
     /** Accepts a platform id or a slug — see {@link IResource} for the full key rule. */
@@ -74,22 +102,17 @@ export declare class Secret extends Construct implements ISecret {
     private readonly explicitSlug;
     private readonly displayName;
     private readonly description;
-    constructor(scope: Construct, id: string, props: {
-        value: SecretValue;
-        slug?: string;
-        name?: string;
-        description?: string;
-        injection?: InjectionRecipeProps;
-    });
+    private readonly team;
+    constructor(scope: Construct, id: string, props: SecretProps);
     private slug;
     /** @internal */
     _resourceId(): string;
-    /**
-     * @internal — `{secretId}` alone, so the secret's own `injection` recipe supplies the broker's header
-     * mutations. A locally-declared secret must actually carry one: binding a recipe-less secret bare would be
-     * denied `recipe_conflict` at hydration, which classifies a binding as "recipe" from the blank header.
-     */
+    /** @internal — read only by the retired rule-level binding's synth error, which names this secret. */
     _credentialBinding(): CredentialBindingData;
+    /** @internal — a fresh copy of the declared hosts, for synth checks that read a declared secret. */
+    _hosts(): string[];
+    /** @internal — whether the declared recipe has a header to present this secret by. */
+    _presentsHeader(): boolean;
     /**
      * A raw `JSON.stringify(secret)` would otherwise walk the circular construct tree; this returns only
      * non-secret identity fields, so accidental logging can never dump the recipe or the tree.

package/dist/constructs/secret.js

@@ -108,6 +108,11 @@ export function cloneValueFrom(valueFrom) {
             },
         };
     }
+    if ("fields" in valueFrom) {
+        return {
+            fields: Object.fromEntries(Object.entries(valueFrom.fields).map(([name, field]) => [name, cloneValueFrom(field)])),
+        };
+    }
     return {
         ecrCredential: {
             accessKeyIdSource: cloneValueFrom(valueFrom.ecrCredential.accessKeyIdSource),
@@ -237,29 +242,117 @@ export class SecretValue {
             ecrCredential: { accessKeyIdSource: accessKeyId.#recipe, secretAccessKeySource: secretAccessKey.#recipe },
         });
     }
+    /**
+     * One secret whose value is a JSON object of named fields, for credentials one request needs together: its
+     * `injection` recipe presents each field as `${secret.<name>}`, so the two headers ride one secret instead
+     * of two secrets that would both cover the host. Each field keeps its own source, so an operator keeps one
+     * environment variable per value; the object is composed only at apply, and only when every field resolves.
+     */
+    static fields(fields) {
+        const entries = Object.entries(fields ?? {});
+        if (entries.length === 0) {
+            throw new Error("SecretValue.fields requires at least one field.");
+        }
+        const recipe = {};
+        for (const [name, value] of entries) {
+            if (!FIELD_NAME.test(name)) {
+                throw new Error(`SecretValue.fields field name ${JSON.stringify(name)} is invalid: a recipe reads it as ` +
+                    `\${secret.<name>}, so it must be non-empty with no whitespace, '.', '{' or '}'.`);
+            }
+            if (!(value instanceof SecretValue)) {
+                throw new Error(`SecretValue.fields field '${name}' must be a SecretValue, such as SecretValue.fromEnv(...).`);
+            }
+            if (containsGatewayKeyRecipe(value.#recipe)) {
+                throw gatewayKeyNestingError("SecretValue.fields", value.#recipe);
+            }
+            recipe[name] = value.#recipe;
+        }
+        return new SecretValue({ fields: recipe });
+    }
     _toValueFrom() {
         return this.#recipe;
     }
 }
+const FIELD_NAME = /^[^\s.{}]+$/;
+/**
+ * A credential's `hosts` use the egress rule host syntax — an exact host, `*.` and a suffix, or `*`, with no
+ * port — and a pattern the platform refuses at write is refused here.
+ */
+export function normalizeCredentialHosts(hosts, label) {
+    if (!Array.isArray(hosts)) {
+        throw new Error(`${label}: 'hosts' must be a list of host patterns, such as ["api.example.com"].`);
+    }
+    for (const host of hosts) {
+        if (typeof host === "string" && hostPatternPort(host)) {
+            throw new Error(`${label}: host pattern ${JSON.stringify(host)} names a port: a credential's hosts name hosts alone, ` +
+                `without a port.`);
+        }
+        if (typeof host !== "string" ||
+            host.trim() === "" ||
+            /[\s/]/.test(host) ||
+            (host.includes(":") && !isIpv6Literal(host))) {
+            throw new Error(`${label}: host pattern ${JSON.stringify(host)} is not a host: write an exact host, *.suffix, or *, ` +
+                `with no scheme, port or path.`);
+        }
+    }
+    return [...hosts];
+}
+/**
+ * The platform's port reading: `host:443` and `[::1]:443` name a port; `[::1]` and `2001:db8::1` are
+ * addresses, whose colons belong to the address.
+ */
+function hostPatternPort(host) {
+    const lastColon = host.lastIndexOf(":");
+    if (lastColon < 0 || !/^\d+$/.test(host.slice(lastColon + 1)))
+        return false;
+    if (host.startsWith("[")) {
+        const close = host.indexOf("]");
+        return close >= 0 && close < lastColon;
+    }
+    return host.indexOf(":") === lastColon;
+}
+function isIpv6Literal(host) {
+    if (host.startsWith("["))
+        return host.length > 2 && host.indexOf("]") === host.length - 1;
+    return !host.includes("]") && host.split(":").length > 2;
+}
+/**
+ * The client-side mirror of the platform's write-time `hosts` checks, so a bad list fails at synth: each
+ * entry is an exact host, `*.` and a suffix, or `*`, and a secret that covers a host needs a recipe header to
+ * be presented by. The platform-origin and object-store refusals need the deployment's own addresses, so they
+ * stay the platform's `400`.
+ */
+function normalizeSecretHosts(hosts, injection, label) {
+    if (hosts === undefined)
+        return [];
+    normalizeCredentialHosts(hosts, label);
+    if (hosts.length > 0 && (injection === undefined || (injection.headers ?? []).length === 0)) {
+        throw new Error(`${label}: a secret with 'hosts' needs an 'injection' recipe with at least one header, which is how it ` +
+            `is presented, such as injection: { headers: [{ name: "Authorization", value: "Bearer \${secret}" }] }.`);
+    }
+    return [...hosts];
+}
 export class Secret extends Construct {
     /** Accepts a platform id or a slug — see {@link IResource} for the full key rule. */
     secretId;
     #valueFrom;
     #injection;
+    #hosts;
     explicitSlug;
     displayName;
     description;
+    team;
     constructor(scope, id, props) {
         super(scope, id);
         validateExplicitSlug(this, props.slug, "secret");
+        const label = `secret '${this.node.path.join("/")}'`;
         this.#valueFrom = props.value._toValueFrom();
-        this.#injection =
-            props.injection === undefined
-                ? undefined
-                : normalizeInjectionRecipe(props.injection, `secret '${this.node.path.join("/")}'`);
+        this.#injection = props.injection === undefined ? undefined : normalizeInjectionRecipe(props.injection, label);
+        this.#hosts = normalizeSecretHosts(props.hosts, this.#injection, label);
         this.explicitSlug = props.slug;
         this.displayName = props.name ?? id;
         this.description = props.description ?? "";
+        this.team = props.team;
         this.secretId = refToken("secret", this.node.path);
     }
     slug() {
@@ -269,19 +362,18 @@ export class Secret extends Construct {
     _resourceId() {
         return this.secretId;
     }
-    /**
-     * @internal — `{secretId}` alone, so the secret's own `injection` recipe supplies the broker's header
-     * mutations. A locally-declared secret must actually carry one: binding a recipe-less secret bare would be
-     * denied `recipe_conflict` at hydration, which classifies a binding as "recipe" from the blank header.
-     */
+    /** @internal — read only by the retired rule-level binding's synth error, which names this secret. */
     _credentialBinding() {
-        if (this.#injection === undefined) {
-            throw new Error(`egress credential cannot bind bare secret '${this.secretId}': it carries no injection recipe. A bare ` +
-                `secret injects the header mutations the secret's own 'injection' block declares — add one to the ` +
-                `secret, or bind it with bearer()/basic()/header()/inject() instead (recipe_conflict).`);
-        }
         return { secretId: this.secretId };
     }
+    /** @internal — a fresh copy of the declared hosts, for synth checks that read a declared secret. */
+    _hosts() {
+        return [...this.#hosts];
+    }
+    /** @internal — whether the declared recipe has a header to present this secret by. */
+    _presentsHeader() {
+        return (this.#injection?.headers ?? []).length > 0;
+    }
     /**
      * A raw `JSON.stringify(secret)` would otherwise walk the circular construct tree; this returns only
      * non-secret identity fields, so accidental logging can never dump the recipe or the tree.
@@ -293,6 +385,8 @@ export class Secret extends Construct {
         const slug = this.slug();
         // `description` is ALWAYS emitted, empty when unset, so it is never omit-masked; the only Secret PATCH
         // rides a value overwrite that sends name+description together, so a clear travels with that write.
+        // `hosts` is ALWAYS emitted, `[]` when undeclared, so apply sends it and a row at `[]` or with other hosts
+        // converges on the declaration.
         // `injection` is emitted only when declared, keeping a recipe-less secret's payload byte-identical, and
         // is DEEP-COPIED because the stored recipe is shared across synths: emitting it by reference would let a
         // caller mutating one returned plan corrupt the validated recipe for every later synth.
@@ -300,7 +394,9 @@ export class Secret extends Construct {
             name: this.displayName,
             slug,
             description: this.description,
+            hosts: [...this.#hosts],
             ...(this.#injection !== undefined ? { injection: cloneInjectionRecipe(this.#injection) } : {}),
+            ...(this.team !== undefined ? { teamId: this.team.teamId } : {}),
         };
         return {
             kind: "secret",

package/dist/constructs/service-account.d.ts

@@ -0,0 +1,12 @@
+import { Construct } from "../core/construct.js";
+import { type TeamMembershipDeclaration } from "./team-membership.js";
+export interface IServiceAccount {
+    readonly serviceAccountId: string;
+}
+export interface ServiceAccountImportProps {
+    memberships: readonly TeamMembershipDeclaration[];
+}
+export declare class ServiceAccount {
+    private constructor();
+    static fromId(scope: Construct, id: string, props: ServiceAccountImportProps): IServiceAccount;
+}

package/dist/constructs/service-account.js

@@ -0,0 +1,23 @@
+// A service account has no slug, so a program names one by its id. The kit never creates one: apply finds
+// the account's membership in the organization and writes the rows declared here as its full set.
+import { teamMembershipRows, TeamMemberships } from "./team-membership.js";
+const SERVICE_ACCOUNT_ID_PATTERN = /^[a-z][a-z0-9]*_[^_]+$/;
+export class ServiceAccount {
+    constructor() {
+        // static-only
+    }
+    static fromId(scope, id, props) {
+        if (!SERVICE_ACCOUNT_ID_PATTERN.test(id)) {
+            throw new Error(`Invalid service account id ${JSON.stringify(id)} for ServiceAccount.fromId: a service account has no ` +
+                `slug, so name it by its platform id, a lowercase prefix word, exactly one '_', then a '_'-free ` +
+                `suffix (e.g. 'svc_01jq…').`);
+        }
+        const constructId = id.toLowerCase().replace(/_/g, "-");
+        if (scope.node.children.some((child) => child.node.id === constructId)) {
+            throw new Error(`service account '${id}' is imported twice. Import each service account once, with its full row set.`);
+        }
+        const rows = teamMembershipRows(`service account '${id}'`, props.memberships);
+        new TeamMemberships(scope, constructId, () => id, { serviceAccountId: id }, rows);
+        return { serviceAccountId: id };
+    }
+}

package/dist/constructs/skill.d.ts

@@ -1,6 +1,6 @@
 import { Construct } from "../core/construct.js";
 import type { PlanResource } from "../core/plan.js";
-import type { ISkill } from "./interfaces.js";
+import type { ISkill, ITeam } from "./interfaces.js";
 export interface SkillProps {
     /** Read whole at synth, and its `SKILL.md` name when an agent is constructed; text-only. */
     source: string;
@@ -8,6 +8,8 @@ export interface SkillProps {
     slug?: string;
     /** Cosmetic only — never used in the prompt or in discovery. */
     displayName?: string;
+    /** Fixed at create; undeclared, the skill is created in Shared. */
+    team?: ITeam;
 }
 /**
  * A directory of instruction text materialized to the runtime by the platform. The apply engine uploads each

package/dist/constructs/skill.js

@@ -47,6 +47,8 @@ export class Skill extends Construct {
         if (this.props.displayName !== undefined) {
             payload.displayName = this.props.displayName;
         }
+        if (this.props.team !== undefined)
+            payload.teamId = this.props.team.teamId;
         return { kind: "skill", path: this.node.path.join("/"), slug, managed: true, payload };
     }
     /** Sorted by path for a deterministic plan. The missing-root-SKILL.md check only pre-empts a server 400. */

package/dist/constructs/team-membership.d.ts

@@ -0,0 +1,43 @@
+import { Construct } from "../core/construct.js";
+import type { PlanResource } from "../core/plan.js";
+import type { IRole, ITeam } from "./interfaces.js";
+/** One role at one scope: one team, or an explicit `allTeams: true`. */
+export type TeamMembershipDeclaration = {
+    readonly team: ITeam;
+    readonly allTeams?: never;
+    readonly role: IRole;
+} | {
+    readonly allTeams: true;
+    readonly team?: never;
+    readonly role: IRole;
+};
+/** The plan wire of one row: exactly one of `teamId` and `allTeams`. */
+export type TeamMembershipRowDocument = {
+    teamId: string;
+    roleId: string;
+} | {
+    allTeams: true;
+    roleId: string;
+};
+export type TeamMembershipPrincipal = {
+    agentId: string;
+} | {
+    serviceAccountId: string;
+};
+export interface TeamMembershipsPayload {
+    principal: TeamMembershipPrincipal;
+    rows: TeamMembershipRowDocument[];
+}
+/**
+ * Checked at declaration, because the platform refuses each with a 400 and an app runs untypechecked: a row
+ * names exactly one scope, a member holds one role per scope, and Owner sits at all teams only.
+ */
+export declare function teamMembershipRows(label: string, declarations: readonly TeamMembershipDeclaration[]): TeamMembershipRowDocument[];
+/** @internal — added beside the principal that declares memberships; never constructed by an app. */
+export declare class TeamMemberships extends Construct {
+    private readonly slugOf;
+    private readonly principal;
+    private readonly rows;
+    constructor(scope: Construct, id: string, slugOf: () => string, principal: TeamMembershipPrincipal, rows: readonly TeamMembershipRowDocument[]);
+    _toPlanResource(): PlanResource;
+}

package/dist/constructs/team-membership.js

@@ -0,0 +1,59 @@
+// The team memberships of an agent or an imported service account, declared in code. A declared list is the
+// principal's full row set: apply adds, changes and removes rows until the live set matches it. A row write
+// never touches the membership's policy assignments, so the policies the platform minted at agent create
+// stay.
+import { Construct } from "../core/construct.js";
+import { OWNER_ROLE_SLUG } from "./role.js";
+/**
+ * Checked at declaration, because the platform refuses each with a 400 and an app runs untypechecked: a row
+ * names exactly one scope, a member holds one role per scope, and Owner sits at all teams only.
+ */
+export function teamMembershipRows(label, declarations) {
+    const rows = [];
+    const scopes = new Set();
+    declarations.forEach((declaration, index) => {
+        const at = `${label}: memberships[${index}]`;
+        const hasTeam = declaration.team !== undefined;
+        const allTeams = declaration.allTeams === true;
+        if (hasTeam === allTeams) {
+            throw new Error(`${at} must name exactly one scope, a team or allTeams: true. A missing scope never means all teams.`);
+        }
+        const roleId = declaration.role.roleId;
+        if (hasTeam && roleId === OWNER_ROLE_SLUG) {
+            throw new Error(`${at} places Owner at one team. Owner is assignable at all teams only; use allTeams: true.`);
+        }
+        const row = hasTeam
+            ? { teamId: declaration.team.teamId, roleId }
+            : { allTeams: true, roleId };
+        const scope = "teamId" in row ? `team ${row.teamId}` : "all teams";
+        if (scopes.has(scope)) {
+            throw new Error(`${at} is a second row at ${scope}. A member holds one role per scope, so combine the two in a custom role.`);
+        }
+        scopes.add(scope);
+        rows.push(row);
+    });
+    // All teams first, then by team reference, so the plan bytes do not depend on declaration order.
+    return rows.sort((a, b) => (scopeKey(a) < scopeKey(b) ? -1 : scopeKey(a) > scopeKey(b) ? 1 : 0));
+}
+function scopeKey(row) {
+    return "teamId" in row ? `1 ${row.teamId}` : "0";
+}
+/** @internal — added beside the principal that declares memberships; never constructed by an app. */
+export class TeamMemberships extends Construct {
+    slugOf;
+    principal;
+    rows;
+    constructor(scope, id, slugOf, principal, rows) {
+        super(scope, id);
+        this.slugOf = slugOf;
+        this.principal = principal;
+        this.rows = rows;
+    }
+    _toPlanResource() {
+        const payload = {
+            principal: { ...this.principal },
+            rows: this.rows.map((row) => ({ ...row })),
+        };
+        return { kind: "team-membership", path: this.node.path.join("/"), slug: this.slugOf(), managed: true, payload };
+    }
+}