cartethyia 2.7.4 → 2.7.5

package/src/providers/integrations/zcode-start-plan/gifts.ts

@@ -0,0 +1,265 @@
+/**
+ * ZCode gift-plan claims (the promo packs).
+ *
+ * This is **not** a check-in: ZCode has no streak, no daily credit and no
+ * status/claim pair like the Buddy family. Its gift plans sit unclaimed on the
+ * account until a claim is posted, and where they are offered is the tricky
+ * part:
+ *
+ * - `/api/v1/zcode-plan/billing/preview` lists the plans the account may claim;
+ * - the app's marketing feed (`/api/v1/marketing/touch`) lists the **banner**
+ *   promos — a weekend build that appears in neither `preview` nor `current`
+ *   while the app shows its banner.
+ *
+ * Both reads and the claim are app-only endpoints: a Bearer token alone is
+ * answered `3001 parameter error` before auth. They need `X-Device-Mid` (the
+ * gateway validates it as a UUID and never binds it to the account) and
+ * `X-ZCode-App-Version`.
+ *
+ * The reply is judged by the body, never the HTTP status: `0` claimed, `1003`
+ * already claimed, `3007` the app's Aliyun attestation is missing.
+ */
+import { createHash } from "node:crypto";
+import { sleep } from "../../../shared/sleep";
+import { asRecord, asTrimmedString } from "../../../shared/coerce";
+import type { ValidatedFetch } from "../../../network/outbound-fetch";
+
+const ZCODE = "https://zcode.z.ai";
+const BILLING = `${ZCODE}/api/v1/zcode-plan/billing`;
+const TOUCH = `${ZCODE}/api/v1/marketing/touch`;
+const APP_VERSION = "3.16.3";
+const PLATFORM = "linux-x64";
+const TIMEOUT_MS = 15_000;
+const CLAIMED_ALREADY = 1003;
+const CAPTCHA = 3007;
+/** The upstream answers these under load; the same call succeeds later. */
+const RETRY_STATUSES = new Set([429, 502, 503, 504]);
+const RETRY_TRIES = 3;
+
+export type ZcodeGiftState = "claimed" | "already_claimed" | "nothing" | "captcha" | "partial" | "error";
+
+export interface ZcodeGiftResult {
+  readonly state: ZcodeGiftState;
+  readonly claimed: readonly string[];
+  readonly detail: string | null;
+}
+
+/** Stable per account — a per-request device id is itself a jitter signal. */
+function deviceMid(accountId: string): string {
+  const hash = createHash("sha256").update(`zcode-device\0${accountId}`).digest("hex");
+  const variant = ((parseInt(hash[16] as string, 16) & 3) | 8).toString(16);
+  return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-${variant}${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+}
+
+function headers(credential: string, accountId: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${credential}`,
+    Accept: "application/json",
+    "Content-Type": "application/json",
+    "X-Device-Mid": deviceMid(accountId),
+    "X-Client-Language": "en-US",
+    "X-ZCode-App-Version": APP_VERSION,
+    "X-Platform": PLATFORM,
+  };
+}
+
+/** The claim actions a marketing delivery offers, and the plan's own name. */
+function bannerClaims(delivery: unknown): { plans: Array<{ planId: string; name: string | null }>; malformed: boolean } {
+  const ids: string[] = [];
+  const names: string[] = [];
+  let malformed = false;
+  const walk = (node: unknown, depth: number): void => {
+    if (depth > 12) return;
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item, depth + 1);
+      return;
+    }
+    const record = asRecord(node);
+    if (!record) return;
+    if (asTrimmedString(record["type"]) === "claim_zcode_plan") {
+      const planId = asTrimmedString(asRecord(record["args"])?.["plan_id"]);
+      if (planId !== undefined) ids.push(planId);
+      else malformed = true;
+    }
+    const plan = asRecord(record["zcode_plan"]);
+    const name = asTrimmedString(plan?.["name"]);
+    if (name !== undefined) names.push(name);
+    for (const value of Object.values(record)) walk(value, depth + 1);
+  };
+  walk(delivery, 0);
+  const name = names[0] ?? null;
+  return { plans: ids.map((planId) => ({ planId, name })), malformed };
+}
+
+/** Only a successful, readable envelope can represent an empty list. */
+async function read(
+  fetcher: ValidatedFetch,
+  url: string,
+  credential: string,
+  accountId: string,
+): Promise<{ ok: boolean; data: Record<string, unknown> | null }> {
+  let response = await fetcher(url, {
+    method: "GET",
+    headers: headers(credential, accountId),
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  for (let attempt = 1; RETRY_STATUSES.has(response.status) && attempt < RETRY_TRIES; attempt += 1) {
+    await sleep(1_500 * attempt);
+    response = await fetcher(url, {
+      method: "GET",
+      headers: headers(credential, accountId),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  }
+  const payload = asRecord(await response.json().catch(() => null));
+  if (!response.ok || !payload || payload["success"] === false) return { ok: false, data: null };
+  const code = payload["code"];
+  if (![0, 200, "0", "200"].includes(code as string | number)) return { ok: false, data: null };
+  // Successful empty lists omit data (or return null) on the app endpoints.
+  if (payload["data"] == null) return { ok: true, data: null };
+  const data = asRecord(payload["data"]);
+  return { ok: data !== undefined && data !== null, data: data ?? null };
+}
+
+/**
+ * Every plan the account may claim, once each. A `null` for a list means it
+ * did not read — never "nothing to claim".
+ */
+async function toClaim(
+  fetcher: ValidatedFetch,
+  credential: string,
+  accountId: string,
+): Promise<{ plans: Array<{ planId: string; name: string | null }>; unread: string[] }> {
+  const plans: Array<{ planId: string; name: string | null }> = [];
+  const unread: string[] = [];
+  const seen = new Set<string>();
+  const add = (planId: string, name: string | null): void => {
+    if (seen.has(planId)) return;
+    seen.add(planId);
+    plans.push({ planId, name });
+  };
+
+  try {
+    const feed = await read(fetcher, `${TOUCH}?seq=0`, credential, accountId);
+    if (!feed.ok) unread.push("marketing feed did not read");
+    else {
+      const deliveries = feed.data?.["deliveries"];
+      if (deliveries != null && (!Array.isArray(deliveries) || deliveries.some((delivery) => !asRecord(delivery)))) {
+        unread.push("marketing feed has no delivery list");
+      }
+      for (const delivery of Array.isArray(deliveries) ? deliveries : []) {
+        const banner = bannerClaims(delivery);
+        if (banner.malformed) unread.push("marketing feed has an invalid claim action");
+        for (const claim of banner.plans) add(claim.planId, claim.name ?? claim.planId);
+      }
+    }
+  } catch {
+    unread.push("marketing feed did not read");
+  }
+
+  try {
+    const preview = await read(
+      fetcher,
+      `${BILLING}/preview?app_version=${APP_VERSION}&platform=${PLATFORM}`,
+      credential,
+      accountId,
+    );
+    if (!preview.ok) unread.push("billing preview did not read");
+    else {
+      const listed = preview.data?.["plans"];
+      if (listed != null && !Array.isArray(listed)) unread.push("billing preview has no plan list");
+      for (const entry of Array.isArray(listed) ? listed : []) {
+        const plan = asRecord(entry);
+        const planId = asTrimmedString(plan?.["plan_id"]);
+        if (planId === undefined) {
+          unread.push("billing preview has an invalid plan");
+          continue;
+        }
+        add(planId, asTrimmedString(plan?.["name"]) ?? planId);
+      }
+    }
+  } catch {
+    unread.push("billing preview did not read");
+  }
+
+  return { plans, unread };
+}
+
+/** Posts one claim and says what the body's own code means. */
+async function claimOne(
+  fetcher: ValidatedFetch,
+  credential: string,
+  accountId: string,
+  planId: string,
+): Promise<"claimed" | "already_claimed" | "captcha" | "failed"> {
+  let response = await fetcher(`${BILLING}/claim`, {
+    method: "POST",
+    headers: headers(credential, accountId),
+    body: JSON.stringify({ plan_id: planId }),
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+  for (let attempt = 1; RETRY_STATUSES.has(response.status) && attempt < RETRY_TRIES; attempt += 1) {
+    await sleep(1_500 * attempt);
+    response = await fetcher(`${BILLING}/claim`, {
+      method: "POST",
+      headers: headers(credential, accountId),
+      body: JSON.stringify({ plan_id: planId }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  }
+  const payload = asRecord(await response.json().catch(() => null));
+  const rawCode = payload?.["code"];
+  const code = typeof rawCode === "string" && rawCode.trim() !== "" ? Number(rawCode) : rawCode;
+  if (payload?.["success"] === false) return "failed";
+  if (code === CAPTCHA) return "captcha";
+  if (code === CLAIMED_ALREADY) return "already_claimed";
+  if (code === 0 && response.ok) return "claimed";
+  return "failed";
+}
+
+/** Claims every gift plan ZCode offers the account. */
+export async function claimZcodeGifts(args: {
+  readonly accountId: string;
+  readonly credential: string;
+  readonly fetcher: ValidatedFetch;
+}): Promise<ZcodeGiftResult> {
+  const { accountId, credential, fetcher } = args;
+  if (!credential) return { state: "error", claimed: [], detail: "account has no credential" };
+  try {
+    const { plans, unread } = await toClaim(fetcher, credential, accountId);
+    if (plans.length === 0) {
+      return unread.length > 0
+        ? { state: "error", claimed: [], detail: unread.join("; ") }
+        : { state: "nothing", claimed: [], detail: null };
+    }
+    const claimed: string[] = [];
+    const already: string[] = [];
+    const captcha: string[] = [];
+    const failed: string[] = [];
+    for (const plan of plans) {
+      const outcome = await claimOne(fetcher, credential, accountId, plan.planId).catch(() => "failed" as const);
+      const name = plan.name ?? plan.planId;
+      if (outcome === "claimed") claimed.push(name);
+      else if (outcome === "already_claimed") already.push(name);
+      else if (outcome === "captcha") captcha.push(name);
+      else failed.push(name);
+    }
+    const detail = [
+      captcha.length ? "CAPTCHA required; claim in the ZCode app" : "",
+      failed.length ? `${failed.length} gift claim(s) failed` : "",
+      ...unread,
+    ].filter(Boolean).join("; ");
+    const outcomes = [claimed.length > 0 || already.length > 0, captcha.length > 0, failed.length > 0 || unread.length > 0];
+    if (outcomes.filter(Boolean).length > 1) return { state: "partial", claimed, detail: detail || null };
+    if (failed.length > 0 || unread.length > 0) return { state: "error", claimed, detail: detail || null };
+    if (captcha.length > 0) return { state: "captcha", claimed, detail: detail || null };
+    if (claimed.length > 0) return { state: "claimed", claimed, detail: null };
+    return { state: "already_claimed", claimed, detail: null };
+  } catch {
+    return {
+      state: "error",
+      claimed: [],
+      detail: "Gift claim request failed",
+    };
+  }
+}

package/src/providers/integrations/zcode-start-plan/oauth.ts

@@ -0,0 +1,154 @@
+/**
+ * Zcode Start Plan sign-in.
+ *
+ * Not an RFC 6749 authorization-code flow: the plan endpoint uses the ZCode
+ * login JWT, not a Coding Plan API key or the separate Z.AI OAuth access token.
+ * It is minted by the CLI device flow:
+ *
+ *   1. `POST /api/v1/oauth/cli/init` (Bearer = a throwaway poll token) returns
+ *      an authorize URL plus a flow id.
+ *   2. The operator opens the URL and approves it in a browser. Nothing comes
+ *      back to this process — the browser lands on ZCode's own callback.
+ *   3. `GET /api/v1/oauth/cli/poll/{flow}` with the same poll token reports
+ *      `status: "ready"` and hands over the JWT.
+ *
+ * There is no refresh grant. Store the credential as issued and discard the
+ * private poll token after completion; revoked sessions require a new sign-in.
+ */
+import * as crypto from "node:crypto";
+
+import type { FetchLike } from "../../authentication/oauth-client";
+import { OAuthDeviceFlow } from "../../authentication/oauth-device-flow";
+import { readJsonResponse } from "../../authentication/oauth-flow-store";
+import type {
+  OAuthDeviceFlowContext,
+  OAuthDevicePollResult,
+  OAuthDeviceStartResult,
+  OAuthExchangeResult,
+} from "../../authentication/oauth-flow-store";
+import { asRecord } from "../../../shared/coerce";
+import { parseJwt } from "../../authentication/jwt-validator";
+
+const ZCODE_BASE = "https://zcode.z.ai" as const;
+const INIT_URL = `${ZCODE_BASE}/api/v1/oauth/cli/init` as const;
+const POLL_BASE = `${ZCODE_BASE}/api/v1/oauth/cli/poll` as const;
+/** Public client id the ZCode CLI ships; not a secret. */
+const ZCODE_CLIENT_ID = "client_P8X5CMWmlaRO9gyO-KSqtg" as const;
+/** ZCode's flow id lives ~300 s; the console polls comfortably inside that. */
+const SESSION_TTL_SECONDS = 900;
+const POLL_INTERVAL_SECONDS = 3;
+/**
+ * Tokens without an exp claim need a storage horizon rather than a real expiry.
+ * The credential resolver treats the resulting api_key account as static.
+ */
+const NO_EXPIRY_MS = 10 * 365 * 24 * 60 * 60 * 1000;
+
+const JSON_HEADERS = {
+  accept: "application/json",
+  "content-type": "application/json",
+} as const;
+
+export class ZcodeStartPlanOAuthClient extends OAuthDeviceFlow {
+  override readonly supportsDeviceCode = true;
+  override readonly supportsBrowserCode = false;
+
+  protected override readonly providerLabel = "Zcode";
+  protected override readonly clientId = ZCODE_CLIENT_ID;
+  protected override readonly tokenUrl = `${ZCODE_BASE}/api/v1/oauth/token`;
+  protected override readonly scopes = "";
+
+  constructor(fetchFn: FetchLike = globalThis.fetch) {
+    super(fetchFn);
+  }
+
+  override async startDeviceAuth(
+    _context?: OAuthDeviceFlowContext,
+  ): Promise<OAuthDeviceStartResult & { providerState: string }> {
+    const pollToken = crypto.randomBytes(32).toString("hex");
+    const response = await this.fetchFn(INIT_URL, {
+      method: "POST",
+      headers: { ...JSON_HEADERS, authorization: `Bearer ${pollToken}` },
+      body: JSON.stringify({ provider: "zai" }),
+    });
+    const payload = asRecord(await readJsonResponse(response, `${this.providerLabel} sign-in`));
+    const data = asRecord(payload?.data);
+    const authorizeUrl = typeof data?.authorize_url === "string" ? data.authorize_url : "";
+    const flowId = typeof data?.flow_id === "string" ? data.flow_id : "";
+    if (!authorizeUrl || !flowId) {
+      throw new Error(`${this.providerLabel} sign-in returned no authorize URL`);
+    }
+    return {
+      verificationUri: authorizeUrl,
+      userCode: "",
+      deviceAuthId: flowId,
+      intervalSeconds: POLL_INTERVAL_SECONDS,
+      expiresInSeconds: SESSION_TTL_SECONDS,
+      providerState: pollToken,
+    };
+  }
+
+  override async pollDeviceAuth(
+    deviceAuthId: string,
+    context?: OAuthDeviceFlowContext,
+  ): Promise<OAuthDevicePollResult> {
+    const pollToken = context?.providerState ?? "";
+    if (!pollToken) {
+      return { status: "failed", reason: "sign-in session lost its poll token" };
+    }
+    const response = await this.fetchFn(`${POLL_BASE}/${encodeURIComponent(deviceAuthId)}`, {
+      headers: { ...JSON_HEADERS, authorization: `Bearer ${pollToken}` },
+    });
+    if (response.status === 404) {
+      return { status: "failed", reason: "sign-in session expired — start again" };
+    }
+    if (response.status === 429) {
+      const retryAfter = Number(response.headers.get("retry-after"));
+      return {
+        status: "slow_down",
+        retryAfterSeconds: Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : POLL_INTERVAL_SECONDS + 5,
+      };
+    }
+    if (response.status >= 500) {
+      return { status: "pending", retryAfterSeconds: POLL_INTERVAL_SECONDS + 5 };
+    }
+    if (!response.ok) {
+      return { status: "failed", reason: `sign-in poll failed (${response.status})` };
+    }
+    const payload = asRecord(await readJsonResponse(response, `${this.providerLabel} sign-in poll`));
+    const code = payload?.["code"];
+    if (!payload || payload["success"] === false ||
+      (code !== undefined && ![0, 200, "0", "200"].includes(code as string | number))) {
+      return { status: "failed", reason: "ZCode sign-in poll was rejected" };
+    }
+    const ready = asRecord(payload?.data);
+    const status = ready?.["status"];
+    if (status !== "ready") {
+      return status === "pending"
+        ? { status: "pending", retryAfterSeconds: POLL_INTERVAL_SECONDS }
+        : { status: "failed", reason: "ZCode sign-in was not authorized" };
+    }
+    const token = typeof ready?.token === "string" ? ready.token : "";
+    if (!token) {
+      return { status: "failed", reason: "ZCode authorized sign-in returned no token" };
+    }
+    const user = asRecord(ready?.user);
+    const email = typeof user?.email === "string" ? user.email : "";
+    const claims = parseJwt(token)?.payload;
+    const userId = claims?.user_id;
+    if (!email && (typeof userId !== "string" || !userId)) {
+      return { status: "failed", reason: "sign-in token has no account identity" };
+    }
+    const result: OAuthExchangeResult = {
+      access: token,
+      // No refresh grant exists for this token; the account is stored as static.
+      refresh: "",
+      expiresAt: new Date(typeof claims?.exp === "number" && Number.isFinite(claims.exp)
+        ? claims.exp * 1000 : Date.now() + NO_EXPIRY_MS),
+      accountLabel: email || String(userId),
+      auth_state: { credentialMode: "api_key", tokenKind: "zcode-plan-jwt" },
+    };
+    return { status: "complete", result };
+  }
+}
+
+export const zcodeStartPlanOAuthClient = new ZcodeStartPlanOAuthClient();

package/src/providers/integrations/zcode-start-plan/provider.ts

@@ -0,0 +1,131 @@
+/**
+ * ZCode Start Plan uses the client's three-block Messages prompt fingerprint.
+ * Caller instructions remain inside the third block; a fourth block is refused.
+ * The bundled prompt/version pair is kept together to preserve upstream bytes.
+ * Reference provenance and bounded live acceptance evidence: provider guide.
+ */
+import { randomUUID } from "node:crypto";
+import { release as osRelease } from "node:os";
+
+import type { ApiKeyProviderSpec } from "../../configured-provider";
+import { defineModel } from "../../provider-model-definition";
+import type { ModelDefinition } from "../../provider-model-definition";
+import { getOrCreateInstallId } from "../shared/install-id";
+import prompt from "./zcode_prompt.json";
+
+const CLI_PREFIX: string = prompt.cliPrefix;
+const STABLE_SECTIONS: readonly string[] = prompt.stableSections;
+const ENVIRONMENT_TEMPLATE: string = prompt.environmentTemplate;
+
+export const ZCODE_START_PLAN_PROVIDER_ID = "zcode-start" as const;
+export const ZCODE_START_PLAN_ENDPOINT_PATH = "/v1/messages" as const;
+export const ZCODE_START_PLAN_BASE_URL = "https://zcode.z.ai/api/v1/zcode-plan/anthropic" as const;
+
+/** Client version the plan endpoint expects in the identity headers. */
+const APP_VERSION = "3.14.5";
+
+type Loose = Record<string, unknown>;
+type TextBlock = { type: "text"; text: string; cache_control?: { type: "ephemeral" } };
+
+function cached(text: string): TextBlock {
+  return { type: "text", text, cache_control: { type: "ephemeral" } };
+}
+
+/** Fills the environment block; the whole text is data, not layout. */
+function environmentBlock(provider: string, model: string): string {
+  return ENVIRONMENT_TEMPLATE.replace("{cwd}", process.cwd())
+    .replace("{platform}", "linux")
+    .replace("{shell}", "bash")
+    .replace("{provider}", provider)
+    .replace("{model}", model);
+}
+
+/** Identity headers every dispatch carries; the adapter adds Authorization. */
+async function identityHeaders(): Promise<Record<string, string>> {
+  return {
+    "user-agent": `ZCode/${APP_VERSION} ai-sdk/anthropic/3.0.81`,
+    "http-referer": "https://zcode.z.ai",
+    "x-title": "Z Code@cli",
+    "x-zcode-app-version": APP_VERSION,
+    "x-zcode-agent": "glm",
+    "x-release-channel": "production",
+    "x-client-language": "en-US",
+    "x-client-timezone": "Asia/Jakarta",
+    "x-platform": "linux",
+    "x-os-category": "linux",
+    "x-os-version": osRelease(),
+    "x-request-id": randomUUID(),
+    "x-zcode-session-type": "main",
+    "x-zcode-trace-id": randomUUID(),
+    // Keep the persisted install-id filename stable across the provider-ID rename.
+    "x-device-mid": await getOrCreateInstallId("zcode-start-plan"),
+    "anthropic-version": "2023-06-01",
+  };
+}
+
+/**
+ * Replaces the payload's system prompt with the ZCode three-block fingerprint.
+ * A caller-supplied system prompt is folded into the third block, after the
+ * environment text: a separate block is rejected with 3012.
+ */
+function dress(payload: Loose, provider = "zcode"): void {
+  const model = typeof payload.model === "string" ? payload.model : "";
+  const own: string[] = [];
+  const system = payload.system;
+  if (typeof system === "string") {
+    if (system.trim()) own.push(system);
+  } else if (Array.isArray(system)) {
+    for (const block of system) {
+      if (
+        block !== null &&
+        typeof block === "object" &&
+        (block as Loose).type === "text" &&
+        typeof (block as Loose).text === "string" &&
+        (block as Loose).text
+      ) {
+        own.push((block as Loose).text as string);
+      }
+    }
+  }
+  const tail = [environmentBlock(provider, model), ...own].join("\n\n");
+  payload.system = [
+    cached(CLI_PREFIX),
+    cached(STABLE_SECTIONS.join("\n\n")),
+    cached(tail),
+  ];
+}
+
+export const ZCODE_START_PLAN_MODELS: readonly ModelDefinition[] = [
+  defineModel({
+    id: "glm-5.3",
+    providerId: ZCODE_START_PLAN_PROVIDER_ID,
+    wireFamily: "messages",
+    endpoint: ZCODE_START_PLAN_ENDPOINT_PATH,
+    ctx: 1_000_000,
+    out: 131_072,
+    reasoning: true,
+    toolCall: true,
+  }),
+  defineModel({
+    id: "glm-5.3-flash",
+    providerId: ZCODE_START_PLAN_PROVIDER_ID,
+    wireFamily: "messages",
+    endpoint: ZCODE_START_PLAN_ENDPOINT_PATH,
+    ctx: 1_000_000,
+    out: 131_072,
+    vision: true,
+    reasoning: true,
+    toolCall: true,
+  }),
+];
+
+/** Start Plan adapter spec: direct upstream, prompt fingerprint, no sidecar. */
+export const ZCODE_START_PLAN_SPEC: ApiKeyProviderSpec = {
+  provider_id: ZCODE_START_PLAN_PROVIDER_ID,
+  base_url: ZCODE_START_PLAN_BASE_URL,
+  endpoint_paths_by_wire_family: { messages: ZCODE_START_PLAN_ENDPOINT_PATH },
+  buildExtraHeaders: () => identityHeaders(),
+  prePayload: (payload) => {
+    dress(payload as Loose);
+  },
+};