@orchestraworks/cli 0.5.1 → 0.5.3

package/dist/constructs/agent.d.ts

@@ -23,6 +23,13 @@ export interface AgentProps {
     harness: HarnessFamily;
     instructions?: string;
     skills?: ISkill[];
+    /**
+     * Whether the platform's managed skills are added after `skills`, which they are unless this is `false` or
+     * the harness is `script` or `custom`. Each managed id is added once, and an id `skills` already names stays
+     * where it is named there. A managed skill is left out when an authored `Skill` in `skills` declares the
+     * same frontmatter `name`, so the agent never installs two skills under one name.
+     */
+    includeManagedSkills?: boolean;
     memoryFiles?: MemoryFile[];
     labels?: Record<string, string>;
     modelSettings?: AgentModelSettings;
@@ -47,11 +54,14 @@ export declare class Agent extends Construct implements IAgent {
     private readonly explicitSlug;
     private readonly displayName;
     private readonly harness;
+    private readonly managedSkillIds;
     constructor(scope: Construct, id: string, props: AgentProps);
     get slug(): string;
     /** @internal */
     _resourceId(): string;
     _toPlanResource(): PlanResource;
+    private receivesManagedSkills;
+    private skillIds;
     static fromSlug(scope: Construct, slug: string): IAgent;
     /**
      * Apply resolves the reference through the shape-opaque `findByIdOrSlug` lookup, so a slug passed here —

package/dist/constructs/agent.js

@@ -2,9 +2,13 @@ import { CreateAgentRequestSyncModeEnum, StandbyCapacityWindowDaysOfWeekEnum, }
 import { Construct } from "../core/construct.js";
 import { validateDeclaredLabels } from "../core/labels.js";
 import { refToken } from "../core/tokens.js";
+import { MANAGED_SKILL_IDS } from "../generated/managed-skills.js";
 import { registerImport, resolveManagedSlug, validateExplicitSlug } from "./references.js";
+import { Skill } from "./skill.js";
 const HARNESS_FAMILIES = ["claude", "codex", "pi", "script", "custom"];
 const SYNC_MODES = Object.values(CreateAgentRequestSyncModeEnum);
+/** The platform serves each managed skill under `skill_<key>`, and `<key>` is that skill's frontmatter `name`. */
+const MANAGED_ID_PREFIX = "skill_";
 /**
  * Checked at runtime as well as in the type: orchestra apps are spawned under `npx tsx`, which transpiles without
  * typechecking, so an app that omits the prop reaches synth with `harness === undefined` and the TypeScript
@@ -75,6 +79,20 @@ function validateStandbyCapacity(label, capacity) {
         }
     });
 }
+/** Checked at runtime for the same reason as the harness: a transpiled app reaches synth untypechecked. */
+function validateIncludeManagedSkills(label, include) {
+    if (include !== undefined && typeof include !== "boolean") {
+        throw new Error(`${label}: includeManagedSkills is ${JSON.stringify(include)}. Set it to true or false, or remove it ` +
+            `to add the managed skills.`);
+    }
+}
+function managedIdsWithoutAuthoredNames(skills) {
+    const authoredNames = new Set(skills.flatMap((skill) => {
+        const name = skill instanceof Skill ? skill._declaredName() : undefined;
+        return name === undefined ? [] : [name];
+    }));
+    return MANAGED_SKILL_IDS.filter((managed) => !authoredNames.has(managed.slice(MANAGED_ID_PREFIX.length)));
+}
 export class Agent extends Construct {
     /** Accepts a platform id or a slug interchangeably — one rule, stated on `IResource`. */
     agentId;
@@ -82,17 +100,20 @@ export class Agent extends Construct {
     explicitSlug;
     displayName;
     harness;
+    managedSkillIds;
     constructor(scope, id, props) {
         super(scope, id);
         validateDeclaredLabels(props.labels, `agent '${this.node.path.join("/")}' labels`);
         validateExplicitSlug(this, props.slug, "agent");
         this.harness = normalizeHarness(`agent '${this.node.path.join("/")}'`, props.harness);
         validateSyncMode(`agent '${this.node.path.join("/")}'`, props.syncMode);
+        validateIncludeManagedSkills(`agent '${this.node.path.join("/")}'`, props.includeManagedSkills);
         // Snapshot at construction so a later mutation of the caller's literal cannot change what synth emits —
         // notably a `labels` key added after the `validateDeclaredLabels` gate above already passed. `skills`
-        // holds references (only each `skillId` is read), so copying the array is enough. Those references are
-        // also why the deep `structuredClone` `connection.ts` uses is unavailable here: an `ISkill` carries a
-        // `_resourceId()` method, which structured clone refuses — and copying an identity would be wrong anyway.
+        // holds references (only each `skillId` and a `Skill`'s declared name are read), so copying the array is
+        // enough. Those references are also why the deep `structuredClone` `connection.ts` uses is unavailable here:
+        // an `ISkill` carries a `_resourceId()` method, which structured clone refuses — and copying an identity
+        // would be wrong anyway.
         this.props = {
             ...props,
             ...(props.skills !== undefined ? { skills: [...props.skills] } : {}),
@@ -102,6 +123,11 @@ export class Agent extends Construct {
             ...(props.standbyCapacity !== undefined ? { standbyCapacity: structuredClone(props.standbyCapacity) } : {}),
         };
         validateStandbyCapacity(`agent '${this.node.path.join("/")}'`, this.props.standbyCapacity);
+        this.managedSkillIds = this.receivesManagedSkills() ? managedIdsWithoutAuthoredNames(this.props.skills ?? []) : [];
+        // Imports, as `Skill.fromId` registers one, so the pre-flight reads that the platform serves each id.
+        for (const managed of this.managedSkillIds) {
+            registerImport(this, { kind: "skill", ref: managed }, managed);
+        }
         this.explicitSlug = props.slug;
         this.displayName = props.name ?? id;
         this.agentId = refToken("agent", this.node.path);
@@ -127,7 +153,7 @@ export class Agent extends Construct {
             environmentId: this.props.environment.environmentId,
             instructions: this.props.instructions ?? "",
             harness: this.harness,
-            skillIds: (this.props.skills ?? []).map((skill) => skill.skillId),
+            skillIds: this.skillIds(),
             memoryFiles: (this.props.memoryFiles ?? []).map((file) => ({
                 path: file.path,
                 content: file.content,
@@ -148,6 +174,15 @@ export class Agent extends Construct {
         };
         return { kind: "agent", path: this.node.path.join("/"), slug, managed: true, payload };
     }
+    // A script agent installs no skill, and the platform refuses `skillIds` on one; a custom agent starts no harness
+    // that reads a skill. Neither gets the managed set.
+    receivesManagedSkills() {
+        return this.harness !== "script" && this.harness !== "custom" && this.props.includeManagedSkills !== false;
+    }
+    skillIds() {
+        const authored = (this.props.skills ?? []).map((skill) => skill.skillId);
+        return [...authored, ...this.managedSkillIds.filter((managed) => !authored.includes(managed))];
+    }
     static fromSlug(scope, slug) {
         registerImport(scope, { kind: "agent", ref: slug }, slug);
         return { agentId: slug, _resourceId: () => slug };

package/dist/constructs/environment.d.ts

@@ -245,6 +245,24 @@ export interface ResourceSpec {
      *  exactly `2 × cpu`. */
     memory?: string;
 }
+/** One hook: a script, at most 64 KiB, and how long it may run. Omitted, the hook's own default bound applies. */
+export interface EnvironmentHook {
+    script: string;
+    timeoutSeconds?: number;
+}
+export interface EnvironmentHooks {
+    /**
+     * Run once as root on each new machine before it registers. Its bound is 1 to 1,800 seconds; omitted, the
+     * deployment's, which is 600 unless the deployment sets another. A machine keeps the hook it was created with.
+     */
+    onStartMachine?: EnvironmentHook;
+    /**
+     * Run once for each agent placed on a machine, as the agent's account in `workingDirectory`, before that
+     * agent's first conversation there. Its bound is 1 to 240 seconds, 120 when omitted. A failure fails the
+     * conversation that waited on it, and the next one runs the hook again.
+     */
+    onStartAgent?: EnvironmentHook;
+}
 export interface EnvironmentProps {
     /** Omitted, each launch uses the compute provider's default image for the runtime. */
     image?: IImage | string;
@@ -253,8 +271,18 @@ export interface EnvironmentProps {
      * runs the worker; a command of your own must still start the worker, or the machine never dials in.
      */
     command?: string[];
-    /** A script run once as root on each new machine before it registers, at most 64 KiB. */
+    /**
+     * A script run once as root on each new machine before it registers, at most 64 KiB.
+     * @deprecated Declare `hooks.onStartMachine`. Both together must name the same script.
+     */
     setup?: string;
+    /**
+     * The folder every conversation's agent starts in: an absolute path for the environment's OS, at most 1,024
+     * characters. The worker creates it for the agent's account when it is missing. Omitted, the agent starts in
+     * the worker's own folder for its harness.
+     */
+    workingDirectory?: string;
+    hooks?: EnvironmentHooks;
     egress: EgressPolicy;
     platform?: PlatformSpec;
     resources?: ResourceSpec;

package/dist/constructs/environment.js

@@ -499,6 +499,12 @@ const LADDER_MEMORY_BY_CPU = {
 /** The Standard capacity — the emitted default when nothing is declared. */
 const STANDARD_CPU = "2";
 const STANDARD_MEMORY = "4G";
+/** A timeout left undeclared is left out, so the platform's default applies and a read of it is no drift. */
+function hookPayload(hook) {
+    if (hook === undefined)
+        return null;
+    return { script: hook.script, ...(hook.timeoutSeconds !== undefined ? { timeoutSeconds: hook.timeoutSeconds } : {}) };
+}
 export class Environment extends Construct {
     /** Accepts a platform id or a slug interchangeably — one rule, stated on `IResource`. */
     environmentId;
@@ -508,6 +514,11 @@ export class Environment extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
         validateExplicitSlug(this, props.slug, "environment");
+        const declaredOnStartMachine = props.hooks?.onStartMachine?.script;
+        if (props.setup !== undefined && declaredOnStartMachine !== undefined && props.setup !== declaredOnStartMachine) {
+            throw new Error(`Environment '${id}' declares both setup and hooks.onStartMachine with different scripts. ` +
+                "Declare hooks.onStartMachine alone: setup is its older name.");
+        }
         // Snapshot at construction so a later mutation of the caller's literal cannot change what synth emits.
         // Each nested plain-data structure is copied one level deeper than the spread; a mount's `volume` stays
         // the same IVolume, since a reference is shared by identity and only its `volumeId` is ever read. Those
@@ -524,6 +535,14 @@ export class Environment extends Construct {
                 : {}),
             ...(props.disks !== undefined ? { disks: props.disks.map((disk) => ({ ...disk })) } : {}),
             ...(props.command !== undefined ? { command: [...props.command] } : {}),
+            ...(props.hooks !== undefined
+                ? {
+                    hooks: {
+                        ...(props.hooks.onStartMachine !== undefined ? { onStartMachine: { ...props.hooks.onStartMachine } } : {}),
+                        ...(props.hooks.onStartAgent !== undefined ? { onStartAgent: { ...props.hooks.onStartAgent } } : {}),
+                    },
+                }
+                : {}),
             // Copied so a key added after the construct accepted the literal cannot ride a later synth into a
             // machine's env.
             ...(props.env !== undefined ? { env: { ...props.env } } : {}),
@@ -555,6 +574,7 @@ export class Environment extends Construct {
             platform.runtime = platformProps.runtime;
         const resources = this.props.resources ?? {};
         const cpu = resources.cpu ?? STANDARD_CPU;
+        const onStartMachine = this.props.hooks?.onStartMachine ?? (this.props.setup ? { script: this.props.setup } : undefined);
         // The egress rules, `ingressPolicy.endpoints`, `volumeMounts` and `env` are ALWAYS emitted — empty when
         // unset — so clearing any of them reconciles through the platform's whole-object PATCH replace instead of
         // being masked as omitted. `env` inherits the known map residual: emptying a declared map as the SOLE
@@ -573,6 +593,12 @@ export class Environment extends Construct {
                     access: endpoint.access,
                 })),
             },
+            // Sent empty when undeclared, and each hook as null, so removing one clears what an earlier apply set.
+            workingDirectory: this.props.workingDirectory ?? "",
+            hooks: {
+                onStartMachine: hookPayload(onStartMachine),
+                onStartAgent: hookPayload(this.props.hooks?.onStartAgent),
+            },
             // The launch facts are declared here and nowhere else: the platform ignores one spelled at the top
             // level of the environment body.
             provisionSpec: {
@@ -580,7 +606,8 @@ export class Environment extends Construct {
                 // leaves the stored value, and only an empty one clears it.
                 image,
                 command: [...(this.props.command ?? [])],
-                setup: this.props.setup ?? "",
+                // The platform refuses a setup that names another script than hooks.onStartMachine in the same body.
+                setup: onStartMachine?.script ?? "",
                 resources: {
                     cpu,
                     // A cpu that names no rung has no `2 x cpu` to look up, so it falls back to the Standard memory: the

package/dist/constructs/skill.d.ts

@@ -2,7 +2,7 @@ import { Construct } from "../core/construct.js";
 import type { PlanResource } from "../core/plan.js";
 import type { ISkill } from "./interfaces.js";
 export interface SkillProps {
-    /** Read at synth; text-only. */
+    /** Read whole at synth, and its `SKILL.md` name when an agent is constructed; text-only. */
     source: string;
     /** When omitted a factory-namespaced slug is derived. */
     slug?: string;
@@ -25,6 +25,11 @@ export declare class Skill extends Construct implements ISkill {
     _toPlanResource(): PlanResource;
     /** Sorted by path for a deterministic plan. The missing-root-SKILL.md check only pre-empts a server 400. */
     private readSourceFiles;
+    /**
+     * @internal The `name` the root `SKILL.md` frontmatter declares, or `undefined` when the file or the field
+     * cannot be read; synth reports an unreadable source itself.
+     */
+    _declaredName(): string | undefined;
     static fromSlug(scope: Construct, slug: string): ISkill;
     static fromId(scope: Construct, id: string): ISkill;
 }

package/dist/constructs/skill.js

@@ -1,7 +1,7 @@
 // The payload mirrors the platform's create request EXCEPT the wire's `files: [{path, fileId}]`: the plan
 // carries the ergonomic authoring shape `{path, content}` and the apply engine does the file choreography.
-// The root `SKILL.md` frontmatter is parsed and validated SERVER-side, so the construct only checks the file
-// set is text, in-cap, and carries a root `SKILL.md`.
+// The root `SKILL.md` frontmatter is validated SERVER-side, so the construct checks only that the file set
+// is text, in-cap, and carries a root `SKILL.md`; it reads the frontmatter's `name` alone, for `Agent`.
 import { readdirSync, readFileSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 import { Construct } from "../core/construct.js";
@@ -73,6 +73,25 @@ export class Skill extends Construct {
         files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
         return files;
     }
+    /**
+     * @internal The `name` the root `SKILL.md` frontmatter declares, or `undefined` when the file or the field
+     * cannot be read; synth reports an unreadable source itself.
+     */
+    _declaredName() {
+        let text;
+        try {
+            text = readFileSync(resolve(this.props.source, ROOT_SKILL_PATH), "utf8");
+        }
+        catch {
+            return undefined;
+        }
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+        const name = frontmatter === null ? null : /^name[ \t]*:[ \t]*(.*?)[ \t]*$/m.exec(frontmatter[1]);
+        if (name === null)
+            return undefined;
+        const quoted = /^(["'])(.*)\1$/.exec(name[1]);
+        return quoted === null ? name[1] : quoted[2];
+    }
     static fromSlug(scope, slug) {
         registerImport(scope, { kind: "skill", ref: slug }, slug);
         return { skillId: slug, _resourceId: () => slug };

package/dist/engine/reconcile.js

@@ -1026,6 +1026,8 @@ async function applyEnvironment(resource, apis, outcomes, applied, reserved, con
     outcomes.push({ path: resource.path, kind: "environment", slug: resource.slug, id, action });
     applied.set(refToken("environment", resource.path.split("/")), id);
 }
+/** The bound the platform stores for an `onStartAgent` hook that declares none. */
+const ON_START_AGENT_DEFAULT_TIMEOUT_SECONDS = 120;
 /**
  * `policyVersion` is server-managed, so it is excluded. The platform leaves an empty `image`, `command` or
  * `setup` out of a read, so the empty value orchestra sends for an undeclared one matches an absent live one.
@@ -1046,7 +1048,19 @@ export function environmentUnchanged(desired, live) {
             }
         }
     }
-    return subsetDeepEqual(compare, live);
+    if (isEmptyLaunchValue(compare.workingDirectory) && isEmptyLaunchValue(live.workingDirectory)) {
+        delete compare.workingDirectory;
+    }
+    // An undeclared bound is compared as the one the platform stores for it, so removing a declared bound is a
+    // change: the agent hook's default, and no bound for the machine hook, whose bound is then the deployment's.
+    const hooks = compare.hooks;
+    for (const [name, undeclared] of [["onStartAgent", ON_START_AGENT_DEFAULT_TIMEOUT_SECONDS], ["onStartMachine", null]]) {
+        const hook = hooks?.[name];
+        if (hook && hook.timeoutSeconds === undefined)
+            hook.timeoutSeconds = undeclared;
+    }
+    // A read leaves out `hooks` when it holds none, which the declared nulls match.
+    return subsetDeepEqual(compare, { ...live, hooks: live.hooks ?? {} });
 }
 function isEmptyLaunchValue(value) {
     return value === undefined || value === null || value === "" || (Array.isArray(value) && value.length === 0);