@302ai/media-studio-cli 0.1.0-beta.7 → 0.1.1-beta.0

package/README.md

@@ -10,16 +10,9 @@ npm install -g @302ai/media-studio-cli
 # requires Node.js >= 22
 ```
 
-Newer, less tested prerelease builds:
-
-```bash
-npm install -g @302ai/media-studio-cli@beta
-```
-
-> **No stable release exists yet.** `latest` points at a prerelease, so both
-> commands above currently install the same build. Staging- and Local-server
-> visibility is gated on the package *version* carrying a prerelease tag — not
-> on the dist-tag — so both are on for either install: **Staging** and
+> **No stable release exists yet.** `latest` currently points at a prerelease.
+> Staging- and Local-server visibility is gated on the package *version*
+> carrying a prerelease tag — not on the dist-tag — so **Staging** and
 > **Local** appear in `msc login` and in `--region` whichever way you install.
 > A future stable release will hide them from both channels.
 
@@ -49,10 +42,12 @@ name:
 ```bash
 msc chat "画一只猫" -r        # -r/--show-reasoning = 展示模型推理过程
 msc chat "hi" --json          # machine-readable output
-msc chat "hi" --session <id>  # 切换到指定会话并设为默认
+msc chat "hi" --session <id>  # 切换到已有会话（先校验存在）并设为默认
+msc chat "hi" --new           # 新建会话并设为默认（id 不复用）
 msc sessions                  # 列出所有会话（标记当前默认 `(current)`）
 msc sessions --json           # 机器可读的原始 JSON 数组
-msc sessions use <id>         # 纯本地切换默认会话（零请求、不校验）
+msc sessions use <id>         # 校验存在后切换默认会话
+msc sessions use --new        # 新建会话并设为默认
 msc skills                    # 列出技能库（--plaza 浏览技能广场）
 msc skills add <slug>          # 从广场安装技能（如 brainstorming，见 --plaza --json 的 slug）
 msc skills rm <command>       # 从技能库移除（-y/--yes 跳过确认）
@@ -86,10 +81,20 @@ whose browser can reach the loopback callback.
   loses a live session.
 - **Later chats** continue that session — upstream remembers the
   conversation by session id, so no history is resent.
-- If the session was deleted elsewhere, the CLI transparently provisions a
-  fresh one and continues — you are never stranded.
-- `--session <id>` switches to a specific session (including web-created
-  ones) and makes it the default, without provisioning.
+- If the current session is gone **before a turn produces any output**, the CLI
+  transparently provisions a fresh one and re-runs the turn — a first-turn
+  failure never strands you.
+- Once a turn has started producing output, a session failure is reported
+  instead: the partial result stands, nothing is re-run, and no replacement
+  session is created (a retry would replay output and re-dispatch tool calls or
+  generation tasks the first attempt may already have started).
+- `--session <id>` switches to an existing session (including web-created
+  ones) and makes it the default. The id is verified upstream first: a missing
+  id fails with a hint, it never provisions a different session behind your
+  back.
+- `--new` creates a fresh session with a newly generated id and makes it the
+  default for later runs. Ids are never reused or adopted: the CLI either uses
+  the id it generated or reports the refusal.
 
 Manual proof of continuity:
 
@@ -324,8 +329,10 @@ msc chat "刚才的数字是几?"     # answers 42
 
 # Session management verification:
 msc sessions                  # shows session list with (current) marker
-msc chat "hi" --session <id>  # switch to specific session
-msc sessions use <id>         # switch default pointer locally
+msc chat "hi" --session <id>  # switch to an existing session
+msc chat "hi" --new           # start a new session
+msc sessions use <id>         # switch default pointer to an existing session
+msc sessions use --new        # create a new session and switch to it
 ```
 
 Without the local server, point at production with

package/dist/index.js

@@ -4284,7 +4284,7 @@ var consola = createConsola2();
 // package.json
 var package_default = {
   name: "@302ai/media-studio-cli",
-  version: "0.1.0-beta.7",
+  version: "0.1.1-beta.0",
   description: "CLI for AI Media Studio — let external agents drive the core media-studio features",
   author: "302.AI",
   license: "Apache-2.0",
@@ -9749,6 +9749,151 @@ function isString(value) {
   return typeof value === "string";
 }
 // ../media-studio-contract/src/err-codes.ts
+var ErrCode = {
+  MISSING_REQUIRED_PARAM: 10001,
+  INVALID_PARAM_FORMAT: 10002,
+  RESOURCE_NOT_FOUND: 10003,
+  METHOD_NOT_ALLOWED: 10004,
+  RATE_LIMITED: 10005,
+  PAYLOAD_TOO_LARGE: 10006,
+  UNSUPPORTED_MEDIA_TYPE: 10007,
+  INTERNAL_ERROR: 10500,
+  DEPENDENCY_UNAVAILABLE: 10501,
+  DATABASE_ERROR: 10502,
+  SERVICE_UNAVAILABLE: 10503,
+  CACHE_UNAVAILABLE: 10504,
+  UNAUTHORIZED: 20001,
+  TOKEN_MISSING: 20002,
+  TOKEN_INVALID: 20003,
+  TOKEN_EXPIRED: 20004,
+  TOKEN_REVOKED: 20005,
+  REFRESH_TOKEN_INVALID: 20006,
+  REFRESH_TOKEN_ROTATED: 20007,
+  VERIFICATION_CODE_INVALID: 20101,
+  VERIFICATION_CODE_EXPIRED: 20102,
+  CODE_SEND_RATE_LIMITED: 20103,
+  CODE_SEND_DAILY_LIMIT: 20104,
+  EMAIL_SEND_FAILED: 20105,
+  EMAIL_ALREADY_REGISTERED: 20106,
+  EMAIL_NOT_REGISTERED: 20107,
+  OAUTH_STATE_INVALID: 20201,
+  OAUTH_CALLBACK_FAILED: 20202,
+  OAUTH_ACCOUNT_ALREADY_BOUND: 20203,
+  SSO_INFO_CONFLICT: 20204,
+  FORBIDDEN: 20301,
+  ADMIN_REQUIRED: 20302,
+  ACCOUNT_DEACTIVATED: 20303,
+  INSUFFICIENT_BALANCE: 30001,
+  CREDIT_FREEZE_FAILED: 30002,
+  FREEZE_RECORD_NOT_FOUND: 30003,
+  FREEZE_ALREADY_SETTLED: 30004,
+  CREDIT_SETTLE_FAILED: 30005,
+  SETTLE_EXCEEDS_FREEZE: 30006,
+  UNFREEZE_FAILED: 30007,
+  CREDIT_BATCH_EXPIRED: 30008,
+  CREDIT_BATCH_NOT_FOUND: 30009,
+  CONCURRENT_MODIFICATION: 30010,
+  PRICING_RULE_NOT_FOUND: 30101,
+  MODEL_PRICE_MISSING: 30102,
+  USAGE_RECORD_DUPLICATED: 30103,
+  BALANCE_CACHE_REBUILD_FAILED: 30104,
+  LEDGER_WRITE_FAILED: 30105,
+  UPSTREAM_ERROR: 40001,
+  UPSTREAM_TIMEOUT: 40002,
+  UPSTREAM_RATE_LIMITED: 40003,
+  UPSTREAM_UNAVAILABLE: 40004,
+  UPSTREAM_AUTH_FAILED: 40005,
+  UPSTREAM_DATA_INVALID: 40006,
+  MODEL_UNSUPPORTED: 40101,
+  MODEL_LABEL_INVALID: 40102,
+  MODEL_PRICE_NOT_CONFIGURED: 40103,
+  MODEL_LABEL_DEPRECATED: 40104,
+  SANDBOX_TOKEN_INVALID: 40201,
+  SANDBOX_TOKEN_EXPIRED: 40202,
+  OSS_TRANSFER_FAILED: 40301,
+  OSS_URL_PRESIGN_FAILED: 40302,
+  PLAN_NOT_FOUND: 50001,
+  PLAN_UNAVAILABLE: 50002,
+  PLAN_PRICE_MISSING: 50003,
+  ORDER_NOT_FOUND: 50101,
+  ORDER_ALREADY_PAID: 50102,
+  ORDER_EXPIRED: 50103,
+  ORDER_AMOUNT_MISMATCH: 50104,
+  ORDER_STATUS_NOT_ALLOWED: 50105,
+  ORDER_CANCEL_FAILED: 50106,
+  ORDER_PENDING_EXISTS: 50107,
+  PAYMENT_FAILED: 50201,
+  PAYMENT_REJECTED: 50202,
+  PAYMENT_METHOD_NOT_FOUND: 50203,
+  WEBHOOK_SIGNATURE_INVALID: 50204,
+  WEBHOOK_EVENT_UNKNOWN: 50205,
+  STRIPE_API_ERROR: 50206,
+  SUBSCRIPTION_NOT_FOUND: 50301,
+  SUBSCRIPTION_STATUS_NOT_ALLOWED: 50302,
+  SUBSCRIPTION_CANCELED: 50303,
+  UPGRADE_PRORATION_FAILED: 50304,
+  DOWNGRADE_NOT_ALLOWED: 50305,
+  AUTO_RENEW_FAILED: 50306,
+  SAVED_CARD_INVALID: 50307,
+  REFUND_NOT_ELIGIBLE: 50401,
+  REFUND_WINDOW_EXPIRED: 50402,
+  REFUND_THRESHOLD_EXCEEDED: 50403,
+  REFUND_FAILED: 50404,
+  TOPUP_SUBSCRIPTION_ONLY: 50501,
+  TOPUP_FROZEN: 50502,
+  TOPUP_NOT_FOUND: 50503,
+  SESSION_NOT_FOUND: 60001,
+  SESSION_ALREADY_EXISTS: 60002,
+  SESSION_STATUS_NOT_ALLOWED: 60003,
+  CHAT_SESSION_EXPIRED: 60004,
+  CHAT_CONTEXT_MISSING: 60005,
+  PROMPT_SUGGESTION_FAILED: 60006,
+  TITLE_GENERATION_FAILED: 60007,
+  CHAT_TASK_NOT_FOUND: 60101,
+  CHAT_TASK_IN_PROGRESS: 60102,
+  CHAT_TASK_CANCELED: 60103,
+  CHAT_TASK_STATUS_NOT_ALLOWED: 60104,
+  SANDBOX_CREATE_FAILED: 60201,
+  SANDBOX_WARMUP_FAILED: 60202,
+  SANDBOX_TIMEOUT: 60203,
+  SANDBOX_UNAVAILABLE: 60204,
+  SANDBOX_COMMAND_FAILED: 60205,
+  SKILL_NOT_FOUND: 60301,
+  SKILL_FILE_INVALID: 60302,
+  SKILL_BUILTIN_IMMUTABLE: 60303,
+  SKILL_UPLOAD_INVALID: 60304,
+  ASSET_NOT_FOUND: 70001,
+  ASSET_GROUP_NOT_FOUND: 70002,
+  ASSET_GROUP_NAME_EXISTS: 70003,
+  ASSET_UPLOAD_FAILED: 70004,
+  ASSET_TOO_LARGE: 70005,
+  ASSET_TYPE_NOT_ALLOWED: 70006,
+  ASSET_GROUP_INVALID: 70007,
+  OSS_UPLOAD_FAILED: 70101,
+  OSS_DOWNLOAD_FAILED: 70102,
+  COVER_UPLOAD_FAILED: 70103,
+  OSS_DELETE_FAILED: 70104,
+  FILE_NOT_FOUND: 70201,
+  FILE_READ_FAILED: 70202,
+  FILE_WRITE_FAILED: 70203,
+  FILE_FORMAT_INVALID: 70204,
+  FILE_FORMAT_TEXT_FILE_ONLY: 70205,
+  FILE_OPERATION_INVALID: 70206,
+  FILE_TARGET_PATH_REQUIRED: 70207,
+  FILE_PATH_COUNT_MISMATCH: 70208,
+  FILE_RENAME_BATCH_UNSUPPORTED: 70209,
+  ADMIN_NOT_LOGGED_IN: 90001,
+  ADMIN_2FA_REQUIRED: 90002,
+  ADMIN_2FA_CODE_INVALID: 90003,
+  ADMIN_2FA_RATE_LIMITED: 90004,
+  ADMIN_FORBIDDEN: 90005,
+  ADMIN_NOT_FOUND: 90006,
+  RISK_CONTROL_TRIGGERED: 90101,
+  RISK_CONTROL_RATE_LIMITED: 90102,
+  RECONCILIATION_MISMATCH: 90103,
+  RECONCILIATION_TASK_FAILED: 90104,
+  AUDIT_LOG_WRITE_FAILED: 90105
+};
 var ERR_NEXT_STEP = {
   10001: "fix_input",
   10002: "fix_input",
@@ -9915,6 +10060,15 @@ var MEDIA_STUDIO_HOSTS = [
   new URL(MEDIA_STUDIO_URLS.cn).hostname,
   new URL(MEDIA_STUDIO_URLS.staging).hostname
 ];
+var APP_ENVS = ["development", "staging", "production"];
+var APP_ENV_SCHEMA = _enum(APP_ENVS);
+var APP_ENV_HOSTS = {
+  staging: [new URL(MEDIA_STUDIO_URLS.staging).hostname],
+  production: [
+    new URL(MEDIA_STUDIO_URLS.default).hostname,
+    new URL(MEDIA_STUDIO_URLS.cn).hostname
+  ]
+};
 
 // ../media-studio-contract/src/skills/activation.ts
 var SKILL_ACTIVATION_MARKER = "%%";
@@ -10018,6 +10172,15 @@ function attempt2(func) {
     return [error, null];
   }
 }
+
+// ../../node_modules/es-toolkit/dist/util/attemptAsync.mjs
+async function attemptAsync(func) {
+  try {
+    return [null, await func()];
+  } catch (error) {
+    return [error, null];
+  }
+}
 // ../../node_modules/ts-pattern/dist/index.js
 var t2 = Symbol.for("@ts-pattern/matcher");
 var e2 = Symbol.for("@ts-pattern/isVariadic");
@@ -16960,6 +17123,15 @@ class ClientSessions {
     const url = `${this.baseUrl}/api/sessions${search ? `?${search}` : ""}`;
     return requestJson(this.customFetch, url, { method: "GET", headers: this.authHeaders() }, ListSessionsResponseSchema, (status) => `Failed to fetch sessions with status ${status}`);
   }
+  async exists(sessionId) {
+    const params = new URLSearchParams({ sessionId, limit: "1" });
+    const [err] = await attemptAsync(() => requestJson(this.customFetch, `${this.baseUrl}/api/sessions/detail?${params.toString()}`, { method: "GET", headers: this.authHeaders() }, unknown2(), (status) => `Failed to verify session ${sessionId} with status ${status}`));
+    if (!err)
+      return true;
+    if (err instanceof ChatUpstreamError && err.status === 404)
+      return false;
+    throw err;
+  }
   async artifacts(query) {
     const params = new URLSearchParams({ sessionId: query.sessionId });
     if (query.taskId !== undefined)
@@ -16997,12 +17169,17 @@ class ClientSessions {
             signal
           });
           if (!response.ok) {
-            await response.body?.cancel().catch(() => {
-              return;
-            });
+            const body = await response.text().catch(() => "");
             const retryable = response.status >= 500 || response.status === 429;
-            if (!retryable)
+            if (!retryable) {
+              if (!state.sessionReady) {
+                state.outcome = {
+                  status: "failed",
+                  error: new ChatUpstreamError(`Session prewarm was rejected with status ${response.status}`, response.status, body)
+                };
+              }
               break;
+            }
             continue;
           }
           await this.consumePrewarmStream(response, state, {
@@ -17021,7 +17198,10 @@ class ClientSessions {
     }
     if (state.outcome)
       return state.outcome;
-    return state.sessionReady ? { status: "fallback", session: state.sessionReady } : { status: "failed" };
+    return state.sessionReady ? { status: "fallback", session: state.sessionReady } : {
+      status: "failed",
+      error: new ChatUpstreamError("Session prewarm never completed: no session_ready event (request retries exhausted or timed out).", 0, "")
+    };
   }
   async consumePrewarmStream(response, state, callbacks) {
     if (!response.body)
@@ -17052,12 +17232,18 @@ class ClientSessions {
           }
           case "done": {
             PrewarmDoneSchema.parse(data);
-            state.outcome = state.sessionReady ? { status: "ready", session: state.sessionReady } : { status: "failed" };
+            state.outcome = state.sessionReady ? { status: "ready", session: state.sessionReady } : {
+              status: "failed",
+              error: new ChatUpstreamError("Session prewarm ended before the session was created upstream.", 0, "")
+            };
             return;
           }
           case "error": {
-            PrewarmErrorSchema.parse(data);
-            state.outcome = state.sessionReady ? { status: "fallback", session: state.sessionReady } : { status: "failed" };
+            const payload = PrewarmErrorSchema.parse(data);
+            state.outcome = state.sessionReady ? { status: "fallback", session: state.sessionReady } : {
+              status: "failed",
+              error: new ChatUpstreamError(payload.message, 0, JSON.stringify({ error: payload }))
+            };
             return;
           }
           default:
@@ -17101,8 +17287,6 @@ var SkillListItemSchema = object2({
   link: string4(),
   descriptionEn: string4(),
   descriptionZh: string4(),
-  tagsEn: array2(string4()),
-  tagsZh: array2(string4()),
   enabled: boolean4(),
   added: boolean4(),
   builtIn: boolean4(),
@@ -17132,8 +17316,6 @@ var PlazaSkillItemSchema = object2({
   command: string4(),
   descriptionEn: string4(),
   descriptionZh: string4(),
-  tagsEn: array2(string4()),
-  tagsZh: array2(string4()),
   link: string4(),
   cover: string4().nullable(),
   version: string4(),
@@ -17807,29 +17989,56 @@ async function resolvePromptAttachments(options) {
 }
 
 // src/services/session.ts
+var SESSION_GONE_ERR_CODES = [
+  ErrCode.SESSION_NOT_FOUND,
+  ErrCode.CHAT_SESSION_EXPIRED
+];
 function isSessionGoneError(err) {
   if (!(err instanceof ChatUpstreamError))
     return false;
+  if (err.errCode !== null) {
+    return SESSION_GONE_ERR_CODES.includes(err.errCode);
+  }
   if (err.status === 404)
     return true;
   return err.body.includes(ERR_SESSION_EXPIRED);
 }
+async function ensureSessionExists(options) {
+  const client = new MediaStudioClient({
+    baseUrl: options.apiBaseUrl,
+    apiKey: options.apiKey
+  });
+  if (await client.sessions.exists(options.sessionId))
+    return;
+  throw new Error(`Session ${options.sessionId} does not exist.
+` + '  → Create one: `msc sessions use --new`, or `msc chat --new "<prompt>"` to also send a prompt.');
+}
+function finalizeProvision(result, spinner) {
+  spinner?.stop();
+  if (result.status === "failed") {
+    throw result.error;
+  }
+  if (result.status === "fallback") {
+    consola.warn("Session created, but sandbox/skill setup did not fully complete. Plain-text chat still works.");
+  }
+  return result.sessionId;
+}
 async function provisionSession(options) {
-  const sessionId = nanoid3();
   const client = new MediaStudioClient({
     baseUrl: options.apiBaseUrl,
     apiKey: options.apiKey
   });
+  const sessionId = nanoid3();
   const outcome = await client.sessions.prewarm({
     sessionId,
     source: "cli",
     onSessionReady: () => saveLastSessionId(sessionId),
-    ...options.onStageChange ? { onStageChange: options.onStageChange } : {}
+    onStageChange: options.onStageChange
   });
-  return M(outcome).with({ status: "ready" }, { status: "fallback" }, ({ status }) => ({
-    status,
-    sessionId
-  })).with({ status: "failed" }, () => ({ status: "failed" })).exhaustive();
+  if (outcome.status === "failed") {
+    return { status: "failed", error: outcome.error };
+  }
+  return { status: outcome.status, sessionId };
 }
 
 // src/lib/skill-refs.ts
@@ -17958,34 +18167,34 @@ function printTerminalMediaAssets(mediaAssets, fullText) {
   process.stdout.write(`====================
 `);
 }
-function finalizeProvision(result, spinner) {
-  spinner.stop();
-  if (result.status === "failed") {
-    throw new Error("Session provisioning failed before any session was created upstream. Try again.");
-  }
-  if (result.status === "fallback") {
-    consola.warn("Session created, but sandbox/skill setup did not fully complete. Continuing with chat.");
-  }
-  return result.sessionId;
+async function provisionNewSession(options) {
+  const onStageChange = options.quiet ? undefined : (stage) => options.spinner.start(PROVISION_STAGE_LABELS[stage]);
+  const result = await provisionSession({
+    apiBaseUrl: options.apiBaseUrl,
+    apiKey: options.apiKey,
+    onStageChange
+  });
+  return finalizeProvision(result, options.spinner);
 }
 async function resolveChatSession(options) {
+  if (options.newSession) {
+    return {
+      sessionId: await provisionNewSession(options),
+      recreateOnGone: false
+    };
+  }
   if (options.sessionFlag) {
     saveLastSessionId(options.sessionFlag);
-    return { sessionId: options.sessionFlag, recreateOnGone: true };
+    return { sessionId: options.sessionFlag, recreateOnGone: false };
   }
   const pointer = readLastSessionId();
   if (pointer) {
     return { sessionId: pointer, recreateOnGone: true };
   }
-  const result = await provisionSession({
-    apiBaseUrl: options.apiBaseUrl,
-    apiKey: options.apiKey,
-    ...options.quiet ? {} : {
-      onStageChange: (stage) => options.spinner.start(PROVISION_STAGE_LABELS[stage])
-    }
-  });
-  const sessionId = finalizeProvision(result, options.spinner);
-  return { sessionId, recreateOnGone: false };
+  return {
+    sessionId: await provisionNewSession(options),
+    recreateOnGone: false
+  };
 }
 async function streamTurn(options) {
   const { args, sessionId, spinner, autoEnabled, attachments } = options;
@@ -18007,6 +18216,9 @@ async function streamTurn(options) {
   const mediaAssets = [];
   let hasFinished = false;
   for await (const ev of stream) {
+    if (ev.type !== "finish" && ev.type !== "error") {
+      options.progress.emitted = true;
+    }
     M(ev).with({ type: "text-delta", delta: z2.string }, ({ delta }) => {
       isThinking = false;
       spinner.stop();
@@ -18108,17 +18320,28 @@ async function runTurn(options) {
   try {
     await streamTurn(options);
   } catch (err) {
-    if (options.recreateOnGone && isSessionGoneError(err)) {
+    const sessionGone = isSessionGoneError(err);
+    if (sessionGone && options.progress.emitted) {
+      throw new Error(`Session ${options.sessionId} failed after this turn had already started.
+` + "  → The partial result above stands; re-run the same prompt to continue in a new session.");
+    }
+    if (sessionGone && !options.recreateOnGone) {
+      throw new Error(`Session ${options.sessionId} does not exist.
+` + '  → Create one: `msc sessions use --new`, or `msc chat --new "<prompt>"` to also send a prompt.');
+    }
+    if (sessionGone) {
       consola.warn(`Session ${options.sessionId} is no longer available. Provisioning a new one...`);
-      const result = await provisionSession({
+      const sessionId = await provisionNewSession({
         apiBaseUrl: options.apiBaseUrl,
         apiKey: resolveApiKey(),
-        ...options.args.json ? {} : {
-          onStageChange: (stage) => options.spinner.start(PROVISION_STAGE_LABELS[stage])
-        }
+        spinner: options.spinner,
+        quiet: options.args.json === true
+      });
+      await streamTurn({
+        ...options,
+        sessionId,
+        apiKey: resolveApiKey()
       });
-      const sessionId = finalizeProvision(result, options.spinner);
-      await streamTurn({ ...options, sessionId, apiKey: resolveApiKey() });
       return;
     }
     throw err;
@@ -18142,7 +18365,11 @@ var chatCommand = defineCommand({
     },
     session: {
       type: "string",
-      description: "Session id to chat with; becomes the default session for future runs"
+      description: "Chat in an existing session id (verified upstream); becomes the default session. A missing id fails — create one with --new"
+    },
+    new: {
+      type: "boolean",
+      description: "Create a new session and chat in it; becomes the default session"
     },
     "show-reasoning": {
       type: "boolean",
@@ -18154,6 +18381,16 @@ var chatCommand = defineCommand({
     const spinner = new AgentSpinner;
     try {
       const apiBaseUrl = resolveApiBaseUrl();
+      if (args.new && args.session) {
+        throw new Error("--new and --session cannot be combined: --session selects an existing session, --new creates one.");
+      }
+      if (args.session) {
+        await ensureSessionExists({
+          apiBaseUrl,
+          apiKey: resolveApiKey(),
+          sessionId: args.session
+        });
+      }
       const { text, skillUrls, autoEnabled } = await resolvePromptSkills({
         prompt: args.prompt,
         apiBaseUrl,
@@ -18172,6 +18409,7 @@ var chatCommand = defineCommand({
       });
       const resolved = await resolveChatSession({
         sessionFlag: args.session,
+        newSession: args.new,
         apiBaseUrl,
         apiKey: resolveApiKey(),
         spinner,
@@ -18182,6 +18420,7 @@ var chatCommand = defineCommand({
         prompt: promptWithAttachments,
         sessionId: resolved.sessionId,
         recreateOnGone: resolved.recreateOnGone,
+        progress: { emitted: false },
         apiBaseUrl,
         apiKey: resolveApiKey(),
         spinner,
@@ -18216,6 +18455,12 @@ images, videos, and multimedia content through AI Media Studio.
   3. Refine in the next turn (multi-turn is automatic):
      msc chat "change the car color to emerald green and add rain"
 
+  Agent Skill (recommended for AI agents):
+    If the agent does not already know how to use msc, install the public
+    Agent Skill before starting a new session:
+      npx -y skills add 302ai/msc-skill --skill msc-skill -g -y
+    This is optional for direct terminal use.
+
 
 2. AUTHENTICATION & SERVERS
 
@@ -18274,8 +18519,16 @@ ${getAvailableRegions().map((r) => `      ${r.key.padEnd(8)} - ${r.url} (${r.des
     "no such file". Remote URLs are not attachments and there is no @url form.
 
   Session Switching:
-    Pass \`--session <id>\` to direct a prompt to a specific existing session
-    and make it your new active session.
+    Pass \`--session <id>\` to direct a prompt to an existing session and make it
+    your new active session. The id is verified against the server first: the
+    CLI only ever selects sessions that exist, so an unknown id fails with a
+    hint instead of silently starting a different conversation.
+
+    Pass \`--new\` to start a fresh session (new id, never reused) and chat in
+    it, ignoring the current default. \`--new\` and \`--session\` are mutually
+    exclusive.
+      msc chat "start over" --new      # new session, new context
+      msc sessions                     # pick an existing id for --session
 
 4. USING SKILLS
 
@@ -18316,7 +18569,13 @@ ${getAvailableRegions().map((r) => `      ${r.key.padEnd(8)} - ${r.url} (${r.des
     including download URLs and model metadata.
 
   msc sessions use <session-id>
-    Switch your active session pointer without sending a prompt.
+    Switch your active session pointer to an existing session. The id is
+    verified against the server; an unknown id fails here and leaves the
+    pointer untouched.
+
+  msc sessions use --new
+    Create a new session upstream and switch the pointer to it, without sending
+    a prompt.
 
   Session deletion is not available in the CLI. Open the corresponding session
   in the Media Studio web app and delete it there manually.
@@ -18369,6 +18628,13 @@ ${getAvailableRegions().map((r) => `      ${r.key.padEnd(8)} - ${r.url}`).join(`
       "nextStep": "relogin"        // recommended action keyword
     }
 
+  Session commands:
+    msc sessions --json              # list: [{ sessionId, note, ... }]
+    msc sessions use <id> --json     # { "sessionId": "string" }
+    msc sessions use --new --json    # { "sessionId": "string" } (newly created)
+    \`--session\`/\`use <id>\` verify the id upstream; an unknown id exits 1 with
+    the \`--new\` hint and leaves the default session untouched.
+
   Recommended next steps:
     relogin          Session expired or missing; run \`msc login\`
     retry_later      Rate limit reached; wait before re-sending
@@ -20361,18 +20627,63 @@ var artifactsCommand = defineCommand({
 var useSessionCommand = defineCommand({
   meta: {
     name: "use",
-    description: "Switch default session (local pointer only, no network request)"
+    description: "Switch the default session to an existing session, or create a fresh one with --new"
   },
   args: {
     sessionId: {
       type: "positional",
-      required: true,
-      description: "Session id to set as default"
+      required: false,
+      description: "Existing session id to set as default"
+    },
+    new: {
+      type: "boolean",
+      description: "Create a new session and make it the default"
+    },
+    json: {
+      type: "boolean",
+      alias: "j",
+      description: "Output machine-readable JSON: { sessionId }"
     }
   },
-  run: ({ args }) => {
-    saveLastSessionId(args.sessionId);
-    consola.success(`Switched default session to ${args.sessionId}`);
+  run: async ({ args }) => {
+    try {
+      const sessionId = args.sessionId;
+      const apiBaseUrl = resolveApiBaseUrl();
+      if (args.new) {
+        if (sessionId) {
+          throw new Error("--new and <session-id> cannot be combined: pass one, not both.");
+        }
+        const result = await provisionSession({
+          apiBaseUrl,
+          apiKey: resolveApiKey()
+        });
+        const created = finalizeProvision(result);
+        if (args.json) {
+          process.stdout.write(`${JSON.stringify({ sessionId: created })}
+`);
+          return;
+        }
+        consola.success(`Created and switched to session ${created}`);
+        return;
+      }
+      if (!sessionId) {
+        throw new Error("Pass the session id to switch to, or --new to create a new session.");
+      }
+      await ensureSessionExists({
+        apiBaseUrl,
+        apiKey: resolveApiKey(),
+        sessionId
+      });
+      saveLastSessionId(sessionId);
+      if (args.json) {
+        process.stdout.write(`${JSON.stringify({ sessionId })}
+`);
+        return;
+      }
+      consola.success(`Switched default session to ${sessionId}`);
+    } catch (err) {
+      reportCommandError(err, { json: args.json });
+    }
   }
 });
 var sessionsCommand = defineCommand({
@@ -20752,6 +21063,8 @@ AGENT QUICKSTART
   1. msc login                   # a human must finish this in a browser; instant if
                                  # that browser is already signed in to the web app
   2. msc chat "a red car" --json # one turn; the conversation continues across runs
+                                 # (--new starts a fresh session, --session <id> picks
+                                 #  an existing one; both are verified)
   3. msc skills --plaza --json   # find a skill, then reference it by leading the
                                  # prompt with /name or %%/name%%
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@302ai/media-studio-cli",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.1-beta.0",
   "description": "CLI for AI Media Studio — let external agents drive the core media-studio features",
   "author": "302.AI",
   "license": "Apache-2.0",