skedyul 1.7.29 → 1.7.31

package/dist/cli/index.js

@@ -2811,6 +2811,34 @@ async function getWorkflowRun(ctx, workplace, workflowRunId) {
   });
 }
 
+// src/cli/api/playground.ts
+async function sendPlaygroundTurn(ctx, workplace, input) {
+  const workplaceToken = await getWorkplaceToken(ctx, workplace);
+  return callCliApi(cliApi(ctx), "/playground", {
+    workplaceId: workplaceToken.workplaceId,
+    action: "send",
+    handle: input.handle,
+    agentId: input.agentId,
+    threadId: input.threadId,
+    content: input.message,
+    currentTime: input.currentTime,
+    contactId: input.contactId,
+    appInstallationId: input.appInstallationId,
+    title: input.title,
+    sandbox: input.sandbox
+  });
+}
+async function inspectPlaygroundSession(ctx, workplace, threadId) {
+  const workplaceToken = await getWorkplaceToken(ctx, workplace);
+  return callCliApi(cliApi(ctx), "/playground", void 0, {
+    method: "GET",
+    query: {
+      workplaceId: workplaceToken.workplaceId,
+      threadId
+    }
+  });
+}
+
 // src/cli/api/apps.ts
 async function linkApp(ctx, input) {
   return callCliApi(cliApi(ctx), "/link", {
@@ -3618,6 +3646,14 @@ var AppAuthInvalidError = class extends Error {
     this.name = "AppAuthInvalidError";
   }
 };
+var TokenRefreshRequiredError = class extends Error {
+  constructor(message = "Access token expired", options) {
+    super(message);
+    this.code = "TOKEN_REFRESH_REQUIRED";
+    this.name = "TokenRefreshRequiredError";
+    this.tokenKey = options?.tokenKey;
+  }
+};
 
 // src/ratelimit/errors.ts
 var RateLimitExceededError = class extends Error {
@@ -3933,6 +3969,24 @@ function createCallToolHandler(registry, state, onMaxRequests) {
           }
         };
       }
+      if (error instanceof TokenRefreshRequiredError) {
+        return {
+          success: false,
+          output: null,
+          billing: { credits: 0 },
+          meta: {
+            success: false,
+            message: error.message,
+            toolName
+          },
+          error: {
+            code: error.code,
+            message: error.message,
+            category: "auth",
+            ...error.tokenKey ? { details: { tokenKey: error.tokenKey } } : {}
+          }
+        };
+      }
       if (error instanceof AppAuthInvalidError) {
         return {
           output: null,
@@ -4686,6 +4740,76 @@ async function handleOAuthCallback(parsedBody, hooks) {
   }
 }
 
+// src/server/handlers/refresh-token-handler.ts
+async function handleRefreshToken(parsedBody, hooks) {
+  if (!hooks?.refresh_token) {
+    return {
+      status: 404,
+      body: { error: "Refresh token handler not configured" }
+    };
+  }
+  const body = parsedBody ?? {};
+  if (!body.env || typeof body.env !== "object" || Array.isArray(body.env)) {
+    return {
+      status: 400,
+      body: {
+        error: {
+          code: -32602,
+          message: "Missing envelope format: expected { env }"
+        }
+      }
+    };
+  }
+  const refreshContext = {
+    env: body.env,
+    invocation: body.invocation,
+    log: createContextLogger()
+  };
+  const requestConfig = {
+    baseUrl: body.env.SKEDYUL_API_URL ?? process.env.SKEDYUL_API_URL ?? "",
+    apiToken: body.env.SKEDYUL_API_TOKEN ?? process.env.SKEDYUL_API_TOKEN ?? ""
+  };
+  try {
+    const refreshHook = hooks.refresh_token;
+    const refreshHandler = typeof refreshHook === "function" ? refreshHook : refreshHook.handler;
+    const result = await withRequestEnv(body.env, async () => {
+      return await runWithConfig(requestConfig, async () => {
+        return await runWithLogContext({ invocation: body.invocation }, async () => {
+          return await refreshHandler(refreshContext);
+        });
+      });
+    });
+    return {
+      status: 200,
+      body: {
+        env: result.env ?? {}
+      }
+    };
+  } catch (err) {
+    if (err instanceof AppAuthInvalidError) {
+      return {
+        status: 401,
+        body: {
+          error: {
+            code: err.code,
+            message: err.message
+          }
+        }
+      };
+    }
+    const errorMessage = err instanceof Error ? err.message : String(err ?? "Unknown error");
+    return {
+      status: 500,
+      body: {
+        error: {
+          code: -32603,
+          message: errorMessage
+        }
+      }
+    };
+  }
+}
+
 // src/types/webhook.ts
 function isRuntimeWebhookContext(ctx) {
   return "appInstallationId" in ctx && ctx.appInstallationId !== void 0;
@@ -4789,6 +4913,33 @@ async function executeWebhookHandler(handle, webhookRegistry, data) {
       });
     });
   } catch (err) {
+    if (err instanceof TokenRefreshRequiredError) {
+      return {
+        status: 200,
+        body: {
+          success: false,
+          error: {
+            code: err.code,
+            message: err.message,
+            category: "auth",
+            ...err.tokenKey ? { details: { tokenKey: err.tokenKey } } : {}
+          }
+        }
+      };
+    }
+    if (err instanceof AppAuthInvalidError) {
+      return {
+        status: 200,
+        body: {
+          success: false,
+          error: {
+            code: err.code,
+            message: err.message,
+            category: "auth"
+          }
+        }
+      };
+    }
     console.error(`Webhook handler '${handle}' error:`, err);
     return {
       status: 500,
@@ -4991,6 +5142,14 @@ async function handleOAuthCallbackRoute(req, ctx) {
   const result = await handleOAuthCallback(parseResult.data, ctx.config.hooks);
   return { status: result.status, body: result.body };
 }
+async function handleRefreshTokenRoute(req, ctx) {
+  const parseResult = parseJsonBody(req);
+  if (!parseResult.success) {
+    return parseResult.error;
+  }
+  const result = await handleRefreshToken(parseResult.data, ctx.config.hooks);
+  return { status: result.status, body: result.body };
+}
 async function handleWebhookRoute(req, handle, ctx) {
   if (!ctx.webhookRegistry) {
     return { status: 404, body: { error: `Webhook handler '${handle}' not found` } };
@@ -5482,6 +5641,21 @@ async function handleBatchOperationRoute(req, ctx) {
         { allowed: true, afterMs: err.retryAfterMs }
       );
     }
+    if (err instanceof TokenRefreshRequiredError) {
+      return softFailureResponse({
+        code: err.code,
+        message: err.message,
+        category: "auth",
+        ...err.tokenKey ? { details: { tokenKey: err.tokenKey } } : {}
+      });
+    }
+    if (err instanceof AppAuthInvalidError) {
+      return softFailureResponse({
+        code: err.code,
+        message: err.message,
+        category: "auth"
+      });
+    }
     log.error("Batch operation failed", err);
     return {
       status: 500,
@@ -5566,6 +5740,9 @@ async function routeRequest(req, ctx) {
     if (req.path === "/oauth_callback" && req.method === "POST") {
       return handleOAuthCallbackRoute(req, ctx);
     }
+    if (req.path === "/refresh_token" && req.method === "POST") {
+      return handleRefreshTokenRoute(req, ctx);
+    }
     if (req.path === "/health" && req.method === "GET") {
       return handleHealthRoute(ctx);
     }
@@ -10552,6 +10729,40 @@ var CRMModelFieldRequirementsSchema = import_v47.z.object({
 var CRMContextSchema = import_v47.z.object({
   models: import_v47.z.record(import_v47.z.string(), CRMModelFieldRequirementsSchema)
 });
+var EntityOperationSchema = import_v47.z.enum(["get", "list", "update", "create", "delete"]);
+var EntityPoliciesSchema = import_v47.z.record(
+  import_v47.z.string(),
+  // entity handle (e.g., "member", "booking")
+  import_v47.z.array(EntityOperationSchema)
+  // allowed operations
+);
+var EvaluatorPreconditionsSchema = import_v47.z.object({
+  toolSucceeded: import_v47.z.boolean().optional(),
+  anyWrittenFields: import_v47.z.array(import_v47.z.string()).optional(),
+  noneOfWrittenFields: import_v47.z.array(import_v47.z.string()).optional(),
+  crm: import_v47.z.array(
+    import_v47.z.object({
+      field: import_v47.z.string(),
+      op: import_v47.z.enum(["eq", "in", "empty", "notEmpty"]),
+      value: import_v47.z.unknown().optional()
+    })
+  ).optional(),
+  skillsLoaded: import_v47.z.array(import_v47.z.string()).optional(),
+  skillsNotLoaded: import_v47.z.array(import_v47.z.string()).optional()
+});
+var SkillEvaluatorSchema = import_v47.z.object({
+  name: import_v47.z.string(),
+  description: import_v47.z.string().optional(),
+  target: import_v47.z.enum(["message", "tool", "entity"]),
+  selector: import_v47.z.string().optional(),
+  criteria: import_v47.z.string(),
+  passThreshold: import_v47.z.number().optional(),
+  checks: import_v47.z.object({
+    requiredArgs: import_v47.z.array(import_v47.z.string()).optional(),
+    forbiddenArgValues: import_v47.z.record(import_v47.z.string(), import_v47.z.array(import_v47.z.unknown())).optional()
+  }).optional(),
+  preconditions: EvaluatorPreconditionsSchema.optional()
+});
 var SkillYAMLSchema = import_v47.z.object({
   // Schema version
   $schema: import_v47.z.string().optional(),
@@ -10562,10 +10773,26 @@ var SkillYAMLSchema = import_v47.z.object({
   description: import_v47.z.string().optional(),
   // Instructions injected into agent system prompt
   instructions: import_v47.z.string(),
+  // Entity policies - declares which entity operations this skill needs
+  // At runtime, these are resolved to CRM tools via AppCrmMap
+  entityPolicies: EntityPoliciesSchema.optional(),
   // Tool configuration - supports both v1 and v2 formats
+  // Use for non-entity tools (MCP tools, system tools)
   tools: SkillToolsSchema.optional(),
   // CRM context - specifies which models/fields to include in schema
   crmContext: CRMContextSchema.optional(),
+  /**
+   * Entity field handles this skill is allowed to write while loaded.
+   * Writing outside this list is reported as an unowned write.
+   */
+  ownedFields: import_v47.z.array(import_v47.z.string()).optional(),
+  /**
+   * Entity field handles this skill must have written before it replies.
+   * Only handles mapped in the install's AppCrmMap are enforced.
+   */
+  requiredWrites: import_v47.z.array(import_v47.z.string()).optional(),
+  // Quality evaluators owned by this skill
+  evaluators: import_v47.z.array(SkillEvaluatorSchema).optional(),
   // Few-shot examples
   examples: import_v47.z.array(SkillExampleSchema).optional()
 });
@@ -10576,8 +10803,12 @@ var SkillYAMLV2Schema = import_v47.z.object({
   version: import_v47.z.string().optional(),
   description: import_v47.z.string().optional(),
   instructions: import_v47.z.string(),
+  entityPolicies: EntityPoliciesSchema.optional(),
   tools: import_v47.z.array(SkillToolDefinitionSchema).optional(),
   crmContext: CRMContextSchema.optional(),
+  ownedFields: import_v47.z.array(import_v47.z.string()).optional(),
+  requiredWrites: import_v47.z.array(import_v47.z.string()).optional(),
+  evaluators: import_v47.z.array(SkillEvaluatorSchema).optional(),
   examples: import_v47.z.array(SkillExampleSchema).optional()
 });
 var SkillVersionWeightSchema = import_v47.z.object({
@@ -10591,17 +10822,24 @@ var SkillRefSchema = import_v47.z.union([
     skill: import_v47.z.string(),
     description: import_v47.z.string().optional(),
     // For AI SDK Agent Skills discovery
-    /** Auto-inject this skill's instructions and tools on every agent turn */
+    /**
+     * Pre-seed this skill as loaded before the first model step, so the agent
+     * does not have to call system:skill:load for it.
+     */
     alwaysLoad: import_v47.z.boolean().optional(),
     // Version selection (pick one):
     version: import_v47.z.number().optional(),
     // Pin to specific version number
     versions: import_v47.z.array(SkillVersionWeightSchema).optional(),
     // A/B testing weights
-    // Legacy support:
-    instructions: import_v47.z.string().optional(),
-    // Inline instructions (deprecated)
-    enabled: import_v47.z.boolean().optional()
+    /**
+     * @deprecated Not implemented. Instructions come from the skill file.
+     */
+    instructions: import_v47.z.string().optional().describe("Not implemented"),
+    /**
+     * @deprecated Not implemented. Remove the skill from `skills` instead.
+     */
+    enabled: import_v47.z.boolean().optional().describe("Not implemented")
   })
 ]);
 var SkillMetadataSchema = import_v47.z.object({
@@ -10630,6 +10868,7 @@ var LoadedSkillSchema = import_v47.z.object({
   name: import_v47.z.string(),
   instructions: import_v47.z.string().optional(),
   description: import_v47.z.string().optional(),
+  entityPolicies: EntityPoliciesSchema.optional(),
   tools: import_v47.z.array(SkillToolDefinitionSchema).optional(),
   examples: import_v47.z.array(SkillExampleSchema).optional()
 });
@@ -10719,7 +10958,11 @@ var ContextValidationResultSchema = import_v48.z.object({
   issues: import_v48.z.array(ContextIssueSchema)
 });
 var SandboxConfigSchema = import_v48.z.object({
-  enabled: import_v48.z.boolean().optional(),
+  /**
+   * @deprecated Not implemented. Sandbox mode is chosen by the caller
+   * (playground, scenario replay, CLI), never by the agent file.
+   */
+  enabled: import_v48.z.boolean().optional().describe("Not implemented"),
   /** @deprecated Use 'context' instead of 'mockContext' */
   mockContext: AgentContextSchema.optional(),
   context: AgentContextSchema.optional()
@@ -10884,24 +11127,94 @@ var ResponsesBehaviorConfigSchema = import_v49.z.object({
    * @default false
    */
   allowSchedule: import_v49.z.boolean().optional(),
+  /**
+   * Whether the agent may skip sending when no reply is warranted.
+   * Platform injects silence rules and exposes system:message:skip.
+   * An explicit skip satisfies requireFinal. Off by default.
+   * @default false
+   */
+  allowSilent: import_v49.z.boolean().optional(),
+  /**
+   * Strip em dashes, smart quotes and bullet leaders from outbound messages.
+   * @default false
+   */
+  humanize: import_v49.z.boolean().optional(),
   /**
    * Message splitting configuration.
-   * Controls whether and how the agent splits responses into multiple messages.
+   * @deprecated Not implemented — accepted but never applied at runtime.
    */
   messageSplitting: import_v49.z.object({
+    enabled: import_v49.z.boolean(),
+    prompt: import_v49.z.string().optional()
+  }).optional().describe("Not implemented"),
+  /**
+   * Response gate configuration.
+   * Automatically detects acknowledgment messages and recommends skipping
+   * responses when a scheduled follow-up already exists.
+   */
+  responseGate: import_v49.z.object({
     /**
-     * Whether to allow natural message splitting.
-     * When true, the agent may split responses into multiple messages
-     * when it improves conversational flow.
+     * Whether the response gate is enabled.
+     * When true, the platform evaluates incoming messages for acknowledgment
+     * patterns and may recommend skipping a response if scheduled follow-ups exist.
+     * @default true (when allowSilent is true)
      */
-    enabled: import_v49.z.boolean(),
+    enabled: import_v49.z.boolean().optional(),
     /**
-     * Custom prompt to override the default message splitting guidance.
-     * If not provided, uses sensible defaults for when to split vs. keep together.
+     * Whether to hard-block sends when gate recommends skip.
+     * When true, system:message:send is blocked unless overrideGate is provided.
+     * When false (default), returns an error encouraging skip but allows override.
+     * @default false
      */
-    prompt: import_v49.z.string().optional()
+    strictMode: import_v49.z.boolean().optional(),
+    /**
+     * Minimum confidence threshold for acknowledgment detection.
+     * Only recommend skip when confidence meets this threshold.
+     * @default 0.7
+     */
+    minAckConfidence: import_v49.z.number().min(0).max(1).optional()
   }).optional()
 });
+var ConversationPolicyLevelSchema = import_v49.z.enum(["off", "prompt", "reject"]);
+var ConversationBehaviorConfigSchema = import_v49.z.object({
+  /** Do not re-ask something the customer already answered. */
+  repeatQuestions: ConversationPolicyLevelSchema.optional(),
+  /** Do not send skill example wording verbatim. */
+  exampleCopy: ConversationPolicyLevelSchema.optional(),
+  /**
+   * A named delay or a promised check-in should produce a scheduled send.
+   * `prompt` reprompts once and accepts the turn either way; `reject` fails
+   * the turn when no scheduled send follows.
+   */
+  namedDelayFollowUp: ConversationPolicyLevelSchema.optional(),
+  /**
+   * Keep the turn to one message. Prompt-only — the hard count comes from
+   * `behavior.responses.maxImmediate`.
+   */
+  oneMessagePerTurn: ConversationPolicyLevelSchema.optional(),
+  /**
+   * Skip rather than send filler. Prompt-only, and only stated when
+   * `behavior.responses.allowSilent` is set.
+   */
+  fillerBan: ConversationPolicyLevelSchema.optional(),
+  /**
+   * A bare acknowledgement does not cancel a pending follow-up. Prompt-only,
+   * and only stated when the thread has pending scheduled messages.
+   */
+  cancelPendingOnAck: ConversationPolicyLevelSchema.optional(),
+  /**
+   * Ask one thing at a time. `reject` blocks a send that asks more than one
+   * question. Defaults to `off` at runtime: an agent that collects several
+   * answers in one message is a legitimate design.
+   */
+  oneQuestionPerMessage: ConversationPolicyLevelSchema.optional(),
+  /**
+   * Fallback when every send this turn was rejected by a policy gate.
+   * `send` releases the last rejected message, `skip` records a skip.
+   * @default "send"
+   */
+  onPolicyRejectExhausted: import_v49.z.enum(["send", "skip"]).optional()
+});
 var SchedulingDelaySchema = import_v49.z.object({
   /** Time unit amount */
   amount: import_v49.z.number(),
@@ -10949,15 +11262,53 @@ var BehaviorConfigV3Schema = import_v49.z.object({
    * Scheduling behavior - controls when the agent schedules follow-up messages.
    * Patterns define triggers like "user indicates they'll return later".
    */
-  scheduling: SchedulingBehaviorConfigSchema.optional()
+  scheduling: SchedulingBehaviorConfigSchema.optional(),
+  /**
+   * Conversation policy - which conversational rules this agent wants, and
+   * whether each is stated in the prompt or enforced at runtime.
+   */
+  conversation: ConversationBehaviorConfigSchema.optional(),
+  /**
+   * Mention a long gap since the last message when one has passed.
+   * @default false
+   */
+  acknowledgeTimeGaps: import_v49.z.boolean().optional(),
+  /**
+   * Gap that counts as long for `acknowledgeTimeGaps`, e.g. "3 days".
+   */
+  timeGapThreshold: import_v49.z.string().optional()
+});
+var AgentSettingV3Schema = import_v49.z.object({
+  /** Setting key, resolved against the install's AgentConfig and env. */
+  key: import_v49.z.string().min(1),
+  /** Human label shown to the model and in the console. */
+  label: import_v49.z.string().optional(),
+  /**
+   * Prompt guidance for this setting. `{{value}}` interpolates the install
+   * value and `{{workplace}}` the workplace name.
+   */
+  guidance: import_v49.z.string().optional(),
+  /**
+   * Marks a setting as supplying a platform value rather than prose.
+   * `persona_name` overrides the agent's persona name for this install.
+   */
+  role: import_v49.z.enum(["persona_name"]).optional()
 });
 var PromptsConfigV3Schema = import_v49.z.object({
   /** Main system prompt with workflow instructions */
   system: import_v49.z.string().optional(),
-  /** Injected during second pass when skills were loaded but tools not used */
-  recovery: import_v49.z.string().optional(),
-  /** Injected during follow-up passes when context needs updating */
-  followUp: import_v49.z.string().optional(),
+  /**
+   * Injected during second pass when skills were loaded but tools not used.
+   * @deprecated Ignored on the durable turn path; only the legacy stream path
+   * reads it. Put the guidance in `system` instead.
+   */
+  recovery: import_v49.z.string().optional().describe("Not implemented"),
+  /**
+   * Injected during follow-up passes when context needs updating.
+   * @deprecated Ignored on the durable turn path; only the legacy stream path
+   * reads it. Put the guidance in `system` instead.
+   */
+  followUp: import_v49.z.string().optional().describe("Not implemented"),
   /** Thread list title generation (system + user template with {{var}} placeholders) */
   titleEnrichment: import_v49.z.object({
     system: import_v49.z.string().optional(),
@@ -10977,18 +11328,23 @@ var AgentYAMLV3Schema = import_v49.z.object({
   // Tools - Always-available tools before any skill loads
   // Examples: system:settings:business_information:get
   tools: import_v49.z.array(AgentToolRefSchema).optional(),
+  /**
+   * Settings - Install-scoped values the agent asks for by key.
+   * Rendered into the prompt with the label and guidance declared here.
+   */
+  settings: import_v49.z.array(AgentSettingV3Schema).optional(),
   /**
    * Events - When the agent activates
    * @deprecated Not yet implemented - this is a planned feature for event-driven agents.
    * Fields are accepted but not used at runtime.
    */
-  events: EventsConfigSchema.optional(),
+  events: EventsConfigSchema.optional().describe("Not implemented"),
   /**
    * Memory - How the agent remembers
    * @deprecated Not yet implemented - this is a planned feature.
    * Fields are accepted but not used at runtime.
    */
-  memory: MemoryConfigV3Schema.optional(),
+  memory: MemoryConfigV3Schema.optional().describe("Not implemented"),
   // Policies - Business rules for the agent
   policies: PoliciesConfigV3Schema.optional(),
   // Runtime - Execution configuration (model + personaModel)
@@ -11031,6 +11387,7 @@ Commands:
   versions          List versions of an agent
   ab                Set A/B testing traffic weights
   rollback          Rollback to a previous version
+  test              Run a playground turn (same path as the web playground)
 
 List Options:
   --workplace, -w   Workplace subdomain (required)
@@ -11041,13 +11398,15 @@ Get Options:
   --json            Output as JSON
 
 Deploy Options:
-  --file, -f        Path to agent definition file (.agent.yml or .agent.json)
+  --file, -f        Path to agent definition file (.agent.yml, .agent.json, or .agent-pack.yaml)
   --workplace, -w   Workplace subdomain (required)
   --draft           Deploy as draft (not published)
+  --upload          Force multipart upload (for large files >500KB)
   --json            Output as JSON
 
-  Supports both legacy (multi-stage) and v3 (skills-based) agent formats.
-  V3 agents use skills, events, and memory instead of stages.
+  Supports v3 (skills-based) agents and agent-pack bundles.
+  Agent-pack files (.agent-pack.yaml) include embedded skills, evaluators, and scenarios.
+  Files larger than 500KB automatically use multipart upload.
 
 Publish Options:
   --workplace, -w   Workplace subdomain (required)
@@ -11070,6 +11429,16 @@ Rollback Options:
   --to              Version number to rollback to
   --json            Output as JSON
 
+Test Options:
+  --workplace, -w   Workplace subdomain (required)
+  --agent, -a       Agent handle (required to start a session)
+  --thread, -t      Continue an existing playground thread
+  --message, -m     User turn to send (omit to inspect the thread)
+  --now             ISO clock the agent should treat as now
+  --contact         Contact ID to impersonate
+  --installation    App installation ID (APP agents)
+  --json            Output as JSON
+
 Examples:
   # List all agents in a workplace
   skedyul agents list --workplace gym-demo
@@ -11094,6 +11463,15 @@ Examples:
 
   # Rollback to previous version
   skedyul agents rollback sales-agent --workplace gym-demo --to 1
+
+  # Playground turn (TESTING thread + runThreadAgentWorkflow)
+  skedyul agents test --agent sales-agent --workplace gym-demo --message "Hey"
+
+  # Continue the thread and pin studio now
+  skedyul agents test --thread th_xxx --workplace gym-demo --message "I'm sick" --now 2026-09-11T22:00:00+10:00
+
+  # Inspect scheduled messages
+  skedyul agents test --thread th_xxx --workplace gym-demo
 `);
 }
 async function getWorkplaceToken4(workplaceSubdomain, serverUrl, cliToken) {
@@ -11344,12 +11722,14 @@ async function handleUpdate2(args2) {
   console.log('Note: "update" is deprecated. Use "deploy" instead.');
   await handleDeploy(args2);
 }
+var MULTIPART_THRESHOLD = 500 * 1024;
 async function handleDeploy(args2) {
   const { flags } = parseArgs(args2);
   const filePath = flags.file || flags.f;
   const workplace = flags.workplace || flags.w;
   const isDraft = Boolean(flags.draft);
   const jsonOutput = Boolean(flags.json);
+  const forceUpload = Boolean(flags.upload);
   if (!filePath) {
     console.error("Error: --file (-f) is required");
     console.error("Usage: skedyul agents deploy --file ./agent.yml --workplace gym-demo");
@@ -11363,11 +11743,25 @@ async function handleDeploy(args2) {
   let agent;
   let content;
   let isV3;
+  let isAgentPack = false;
   try {
-    const result = await loadAgentFile(filePath);
-    agent = result.agent;
-    content = result.content;
-    isV3 = result.isV3;
+    const absolutePath = path22.resolve(filePath);
+    content = fs22.readFileSync(absolutePath, "utf-8");
+    const rawContent = (0, import_yaml2.parse)(content);
+    isAgentPack = rawContent?.kind === "skedyul.agent-pack";
+    if (isAgentPack) {
+      const agentObj = rawContent.agent;
+      if (!agentObj) {
+        throw new Error('Agent-pack missing "agent" field');
+      }
+      agent = agentObj;
+      isV3 = true;
+    } else {
+      const result = await loadAgentFile(filePath);
+      agent = result.agent;
+      content = result.content;
+      isV3 = result.isV3;
+    }
   } catch (error) {
     if (jsonOutput) {
       console.log(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
@@ -11388,37 +11782,46 @@ async function handleDeploy(args2) {
     }
     process.exit(1);
   }
+  const fileSize = Buffer.byteLength(content, "utf8");
+  const useMultipart = forceUpload || fileSize > MULTIPART_THRESHOLD || isAgentPack;
   if (!jsonOutput) {
     let agentType;
-    if (isV3) {
+    if (isAgentPack) {
+      agentType = "agent-pack (bundled)";
+    } else if (isV3) {
       agentType = "v3 (skills-based)";
     } else {
       agentType = isMultiStageAgent(agent) ? "multi-stage" : "single-stage";
     }
     console.log("");
     console.log(`Deploying ${agentType} agent "${agent.name}" to ${workplace}${isDraft ? " (draft)" : ""}`);
+    if (useMultipart) {
+      console.log(`  Using multipart upload (${(fileSize / 1024).toFixed(1)} KB)`);
+    }
     console.log("");
   }
   try {
-    const response = await fetch(`${serverUrl}/api/cli/agents`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${token}`
-      },
-      body: JSON.stringify({
+    let result;
+    if (useMultipart) {
+      result = await deployAgentMultipart({
+        serverUrl,
+        token,
         workplaceId: workplaceToken.workplaceId,
         subdomain: workplaceToken.workplaceSubdomain,
-        action: "deploy",
-        yamlContent: content,
+        filePath,
+        content,
         publish: !isDraft
-      })
-    });
-    if (!response.ok) {
-      const errorData = await response.json().catch(() => ({}));
-      throw new Error(errorData.error || `Request failed: ${response.statusText}`);
+      });
+    } else {
+      result = await deployAgentJson({
+        serverUrl,
+        token,
+        workplaceId: workplaceToken.workplaceId,
+        subdomain: workplaceToken.workplaceSubdomain,
+        content,
+        publish: !isDraft
+      });
     }
-    const result = await response.json();
     if (!result.success) {
       throw new Error(result.error || "Failed to deploy agent");
     }
@@ -11446,6 +11849,12 @@ async function handleDeploy(args2) {
         console.log(`  Tools:     ${result.agent.tools.length} bound`);
       }
     }
+    if (result.deployedSkills?.length) {
+      console.log(`  Skills:    ${result.deployedSkills.length} deployed`);
+      for (const skill of result.deployedSkills) {
+        console.log(`    - ${skill.handle} v${skill.version}`);
+      }
+    }
     console.log("");
   } catch (error) {
     if (jsonOutput) {
@@ -11456,6 +11865,50 @@ async function handleDeploy(args2) {
     process.exit(1);
   }
 }
+async function deployAgentJson(params) {
+  const response = await fetch(`${params.serverUrl}/api/cli/agents`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${params.token}`
+    },
+    body: JSON.stringify({
+      workplaceId: params.workplaceId,
+      subdomain: params.subdomain,
+      action: "deploy",
+      yamlContent: params.content,
+      publish: params.publish
+    })
+  });
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    throw new Error(errorData.error || `Request failed: ${response.statusText}`);
+  }
+  return response.json();
+}
+async function deployAgentMultipart(params) {
+  const formData = new FormData();
+  const blob = new Blob([params.content], { type: "text/yaml" });
+  const fileName = path22.basename(params.filePath);
+  formData.append("file", blob, fileName);
+  formData.append("metadata", JSON.stringify({
+    workplaceId: params.workplaceId,
+    subdomain: params.subdomain,
+    publish: params.publish
+  }));
+  const response = await fetch(`${params.serverUrl}/api/cli/agents/upload`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${params.token}`
+    },
+    body: formData
+  });
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    throw new Error(errorData.error || `Request failed: ${response.statusText}`);
+  }
+  return response.json();
+}
 async function handlePublish(args2) {
   const { flags, positional } = parseArgs(args2);
   const handle = positional[0];
@@ -11746,6 +12199,132 @@ async function handleRollback(args2) {
     process.exit(1);
   }
 }
+async function handleTest(args2) {
+  const { flags } = parseArgs(args2);
+  const workplace = flags.workplace || flags.w;
+  const handle = flags.agent || flags.a;
+  const threadId = flags.thread || flags.t;
+  const message = flags.message || flags.m;
+  const currentTime = flags.now;
+  const contactId = flags.contact;
+  const appInstallationId = flags.installation;
+  const jsonOutput = Boolean(flags.json);
+  if (!workplace) {
+    console.error("Error: --workplace (-w) is required");
+    console.error(
+      'Usage: skedyul agents test --workplace gym-demo --agent sales-agent --message "Hey"'
+    );
+    process.exit(1);
+  }
+  if (!threadId && !handle) {
+    console.error("Error: --agent (-a) is required when starting a session");
+    console.error(
+      'Usage: skedyul agents test --workplace gym-demo --agent sales-agent --message "Hey"'
+    );
+    process.exit(1);
+  }
+  if (!message && !threadId) {
+    console.error("Error: --message (-m) is required when starting a session");
+    process.exit(1);
+  }
+  const { token, serverUrl } = ensureAuth3();
+  const ctx = { token, serverUrl };
+  try {
+    if (!message) {
+      const result2 = await inspectPlaygroundSession(ctx, workplace, threadId);
+      if (!result2.success) {
+        throw new Error(result2.error || "Failed to inspect playground session");
+      }
+      if (jsonOutput) {
+        console.log(JSON.stringify(result2, null, 2));
+        return;
+      }
+      console.log("");
+      console.log(`Playground ${result2.threadId}`);
+      if (result2.agentHandle || result2.agentName) {
+        console.log(`Agent     ${result2.agentHandle ?? result2.agentName}`);
+      }
+      console.log("");
+      for (const row of result2.messages) {
+        const who = row.role === "user" ? "USER " : "AGENT";
+        console.log(`${who}  ${row.content}`);
+      }
+      if (result2.scheduledMessages.length === 0) {
+        console.log("");
+        console.log("SCHED  (none)");
+      } else {
+        console.log("");
+        for (const row of result2.scheduledMessages) {
+          console.log(`SCHED  ${row.status} ${row.scheduledAt} ${row.content}`);
+        }
+      }
+      for (const row of result2.sendCalls) {
+        if (row.sendAt != null) {
+          console.log(`SENDAT ${String(row.sendAt)} ${row.content ?? ""}`);
+        }
+      }
+      if (result2.schedulingCheck) {
+        console.log(
+          `CHECK  ${result2.schedulingCheck.passed ? "pass" : "fail"} ${result2.schedulingCheck.reason}`
+        );
+      }
+      console.log("");
+      return;
+    }
+    const result = await sendPlaygroundTurn(ctx, workplace, {
+      handle,
+      threadId,
+      message,
+      currentTime,
+      contactId,
+      appInstallationId
+    });
+    if (!result.success) {
+      throw new Error(result.error || "Failed to run playground turn");
+    }
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log("");
+    console.log(`THREAD ${result.threadId}`);
+    console.log(`STATUS ${result.status}`);
+    if (result.currentTime) {
+      console.log(`NOW    ${result.currentTime}`);
+    }
+    if (result.agentResponse) {
+      console.log(`AGENT  ${result.agentResponse}`);
+    } else {
+      console.log("AGENT  (no immediate SMS)");
+    }
+    if (result.scheduledMessages.length === 0) {
+      console.log("SCHED  (none)");
+    } else {
+      for (const row of result.scheduledMessages) {
+        console.log(`SCHED  ${row.status} ${row.scheduledAt} ${row.content}`);
+      }
+    }
+    if (result.schedulingCheck) {
+      console.log(
+        `CHECK  ${result.schedulingCheck.passed ? "pass" : "fail"} ${result.schedulingCheck.reason}`
+      );
+    }
+    console.log("");
+  } catch (error) {
+    if (jsonOutput) {
+      console.log(
+        JSON.stringify({
+          error: error instanceof Error ? error.message : String(error)
+        })
+      );
+    } else {
+      console.error(
+        `Error: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    process.exit(1);
+  }
+}
 async function agentsCommand(args2) {
   const subcommand = args2[0];
   if (!subcommand || subcommand === "--help" || subcommand === "-h") {
@@ -11781,6 +12360,9 @@ async function agentsCommand(args2) {
     case "rollback":
       await handleRollback(subArgs);
       break;
+    case "test":
+      await handleTest(subArgs);
+      break;
     default:
       console.error(`Error: Unknown subcommand: ${subcommand}`);
       console.error("Run 'skedyul agents --help' for usage information.");
@@ -12979,8 +13561,11 @@ Deploy Options:
   --workplace, -w   Workplace subdomain (required)
   --draft           Deploy as draft (not published)
   --label           Version label (e.g., "experiment-shorter-prompts")
+  --upload          Force multipart upload (for large files >500KB)
   --json            Output as JSON
 
+  Note: Files larger than 500KB automatically use multipart upload.
+
 Publish Options:
   --workplace, -w   Workplace subdomain (required)
   --version, -v     Version number to publish (required)
@@ -13187,6 +13772,7 @@ async function handleGet3(args2) {
     process.exit(1);
   }
 }
+var MULTIPART_THRESHOLD2 = 500 * 1024;
 async function handleDeploy2(args2) {
   const { flags } = parseArgs(args2);
   const filePath = flags.file || flags.f;
@@ -13194,6 +13780,7 @@ async function handleDeploy2(args2) {
   const isDraft = Boolean(flags.draft);
   const versionLabel = flags.label;
   const jsonOutput = Boolean(flags.json);
+  const forceUpload = Boolean(flags.upload);
   if (!filePath) {
     console.error("Error: --file (-f) is required");
     console.error("Usage: skedyul skills deploy --file ./skill.yml --workplace crux");
@@ -13230,36 +13817,38 @@ async function handleDeploy2(args2) {
     }
     process.exit(1);
   }
+  const fileSize = Buffer.byteLength(content, "utf8");
+  const useMultipart = forceUpload || fileSize > MULTIPART_THRESHOLD2;
   if (!jsonOutput) {
     console.log("");
     console.log(`Deploying skill "${skill.name}" to ${workplace}${isDraft ? " (draft)" : ""}`);
+    if (useMultipart) {
+      console.log(`  Using multipart upload (${(fileSize / 1024).toFixed(1)} KB)`);
+    }
     console.log("");
   }
   try {
-    const response = await fetch(`${serverUrl}/api/cli/skills`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${token}`
-      },
-      body: JSON.stringify({
-        action: "deploy",
+    let result;
+    if (useMultipart) {
+      result = await deploySkillMultipart({
+        serverUrl,
+        token,
         workplaceId: workplaceToken.workplaceId,
-        yamlContent: content,
+        filePath,
+        content,
         publish: !isDraft,
         versionLabel
-      })
-    });
-    if (!response.ok) {
-      const errorData = await response.json().catch(() => ({}));
-      if (errorData.details) {
-        const detailsStr = errorData.details.map((d) => `  - ${d.path}: ${d.message}`).join("\n");
-        throw new Error(`${errorData.error}
-${detailsStr}`);
-      }
-      throw new Error(errorData.error || `Request failed: ${response.statusText}`);
+      });
+    } else {
+      result = await deploySkillJson({
+        serverUrl,
+        token,
+        workplaceId: workplaceToken.workplaceId,
+        content,
+        publish: !isDraft,
+        versionLabel
+      });
     }
-    const result = await response.json();
     if (!result.success) {
       throw new Error(result.error || "Failed to deploy skill");
     }
@@ -13286,6 +13875,60 @@ ${detailsStr}`);
     process.exit(1);
   }
 }
+async function deploySkillJson(params) {
+  const response = await fetch(`${params.serverUrl}/api/cli/skills`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${params.token}`
+    },
+    body: JSON.stringify({
+      action: "deploy",
+      workplaceId: params.workplaceId,
+      yamlContent: params.content,
+      publish: params.publish,
+      versionLabel: params.versionLabel
+    })
+  });
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    if (errorData.details) {
+      const detailsStr = errorData.details.map((d) => `  - ${d.path}: ${d.message}`).join("\n");
+      throw new Error(`${errorData.error}
+${detailsStr}`);
+    }
+    throw new Error(errorData.error || `Request failed: ${response.statusText}`);
+  }
+  return response.json();
+}
+async function deploySkillMultipart(params) {
+  const formData = new FormData();
+  const blob = new Blob([params.content], { type: "text/yaml" });
+  const fileName = path24.basename(params.filePath);
+  formData.append("file", blob, fileName);
+  formData.append("metadata", JSON.stringify({
+    workplaceId: params.workplaceId,
+    publish: params.publish,
+    versionLabel: params.versionLabel
+  }));
+  const response = await fetch(`${params.serverUrl}/api/cli/skills/upload`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${params.token}`
+    },
+    body: formData
+  });
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    if (errorData.details) {
+      const detailsStr = errorData.details.map((d) => `  - ${d.path}: ${d.message}`).join("\n");
+      throw new Error(`${errorData.error}
+${detailsStr}`);
+    }
+    throw new Error(errorData.error || `Request failed: ${response.statusText}`);
+  }
+  return response.json();
+}
 async function handlePublish2(args2) {
   const { flags, positional } = parseArgs(args2);
   const handle = positional[0];
@@ -14381,7 +15024,7 @@ COMMANDS
   invoke     Invoke a tool on a hosted app version
   instances  Manage CRM instances (list, get, create, update, delete)
   crm        Manage CRM schemas (push, pull, diff, models)
-  agents     Manage agents (list, get, push)
+  agents     Manage agents (list, get, deploy, test)
   skills     Manage skills (list, get, deploy, publish, versions, delete)
   workflows  Manage workflows (list, get, deploy, run, publish, pull)
   event        Emit test app events to the event bus (CLI testing)