unfazed 0.6.0 → 0.8.0

package/dist/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;CA0B/C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;CAyBrC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;;;;;;;;;;;;;CAa9C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;;;;;;;;;;;CAW7C,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;;;;;;CAM9C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;;;;;;;;;;;;CAY5C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;;;;;;;;;;;;;;CAc9C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;;;;;;;;;;;;;;;;;CAiBxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;;;;;;;;;;;;;;;;;;CAkBvC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;;;;;;CAMzC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;;;;;;;;CAQ/C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;;;;;;;;CAQ9C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;;;;;;CAM5C,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;;;;;;;;;;;CAW7C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAO,CAAC;;;;;;CAMnD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;;;;;;;;;;;;;CAa9C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;;;;;;CAM3C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;;;;;;;;;;;;;;;;CAgBvC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;;;;;;;;;;;;;;;;;;;CAmB5C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;;;;;;;;;;;;CAY1C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;;;;;;;;;;;;;CAa/C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;;;;;;;;;;;CAW7C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;;;;;;;;;;;CAW1C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;;;;;;CAM/C,CAAC,CAAC;AAEH;;;;;;;4EAO4E;AAE5E,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;;;;;;;;;;;;;;CAc9C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAC;;;;;;;;;;;;;;CAcjD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,0BAA0B,GAAG,OAAO,CAAC;;;;;;CAMjD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;;;;;;;;;;;;CAY/C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;;;;;;;;;;;;;;CAcxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;;;;;;;;;;;;;;CAc3C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;;;;;;CAM3C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;;;;;;CAM5C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;;;;;;;;;;;;CAYzC,CAAC,CAAC;AAEH;;;;;;;;;4EAS4E;AAE5E,6CAA6C;AAC7C,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;;;;;;CAMxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;;;;;;CAMrC,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;;;;;;;;;CAStC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;;;;;;;;;;;;;CAavC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;;;;;;CAMxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;;;;;;;;;;;;CAYxC,CAAC,CAAC;AAEH,wFAAwF;AACxF,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;;;;;;;;CAQzC,CAAC,CAAC;AAEH,6DAA6D;AAC7D,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;;;;;;;;;;CAU5C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;;;;;;CAMxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;;;;;;CAM1C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,OAAO,CAAC;;;;;;;;;CAS/C,CAAC,CAAC","sourcesContent":["/**\n * Every GraphQL document the workflow layer sends.\n *\n * These are wrapped in `graphql(...)` so graphql-codegen validates them\n * against the vendored schema at codegen time and emits exact result/variable\n * types. A field that stops existing server-side turns into a compile error\n * here rather than a runtime surprise in an agent's script.\n *\n * The one document NOT defined here is the batched file write: it has a\n * variable number of aliased root fields, so it is assembled at runtime in\n * `unfazed.ts`. See the comment there.\n */\nimport { graphql } from \"./generated/gql.js\";\n\n/**\n * Deployment fields the SDK returns everywhere.\n *\n * `id` + `aliasRevision` + `aliasHeld` are the rollback compare-and-swap\n * triple; `previewUrl` is the immutable by-id URL you can verify BEFORE the\n * alias moves; `error` carries the build failure text when status is FAILED.\n */\nexport const DeploymentFieldsFragment = graphql(`\n  fragment DeploymentFields on Deployment {\n    id\n    workspaceID\n    kind\n    runtime\n    alias\n    serviceMode\n    healthPath\n    cronSchedule\n    cronPath\n    url\n    previewUrl\n    sshCommand\n    aliasHeld\n    aliasRevision\n    status\n    error\n    filesCount\n    sizeBytes\n    size\n    spaMode\n    gitRepo\n    gitCommit\n    createdAt\n  }\n`);\n\nexport const WhoamiDocument = graphql(`\n  query SdkWhoami {\n    whoami {\n      kind\n      userID\n      name\n      agentID\n      agentName\n      claimed\n      claimedBy\n      scopes\n      expiresAt\n      usage {\n        month\n        requests\n        limit\n      }\n      resources {\n        workspaces\n        workspaceLimit\n        services\n        serviceLimit\n      }\n    }\n  }\n`);\n\nexport const CreateWorkspaceDocument = graphql(`\n  mutation SdkCreateWorkspace($name: String!) {\n    createWorkspace(input: { name: $name }) {\n      workspace {\n        id\n        name\n        ownerId\n        projectId\n        createdAt\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const ListWorkspacesDocument = graphql(`\n  query SdkListWorkspaces {\n    workspaces {\n      id\n      name\n      ownerId\n      projectId\n      createdAt\n      updatedAt\n    }\n  }\n`);\n\n/**\n * Deleting a workspace, with the deployment cascade made explicit.\n *\n * `withDeployments` is not decoration: without it the server REFUSES while the\n * workspace has any deployment history at all — including FAILED records —\n * with `workspace %q still has deployments; delete them first`. A workspace\n * that was ever deployed is therefore undeletable through the bare mutation,\n * so the SDK always sends the flag and lets the caller choose the value.\n */\nexport const DeleteWorkspaceDocument = graphql(`\n  mutation SdkDeleteWorkspace($workspaceID: ID!, $withDeployments: Boolean) {\n    deleteWorkspace(input: { workspaceID: $workspaceID, withDeployments: $withDeployments }) {\n      ok\n    }\n  }\n`);\n\nexport const WriteTextFileDocument = graphql(`\n  mutation SdkWriteTextFile($workspaceID: ID!, $path: String!, $text: String!) {\n    writeWorkspaceTextFile(input: { workspaceID: $workspaceID, path: $path, text: $text }) {\n      file {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const WriteBase64FileDocument = graphql(`\n  mutation SdkWriteBase64File($workspaceID: ID!, $path: String!, $contentBase64: String!) {\n    writeWorkspaceBase64File(\n      input: { workspaceID: $workspaceID, path: $path, contentBase64: $contentBase64 }\n    ) {\n      file {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const ListFilesDocument = graphql(`\n  query SdkListFiles($input: ListWorkspaceFilesInput!) {\n    workspaceFilesPage(input: $input) {\n      items {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n      total\n      limit\n      offset\n      hasMore\n      nextOffset\n    }\n  }\n`);\n\nexport const ReadFileDocument = graphql(`\n  query SdkReadFile($input: ReadWorkspaceFileInput!) {\n    readWorkspaceFile(input: $input) {\n      text\n      offset\n      limit\n      totalBytes\n      truncated\n      nextOffset\n      file {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const DeleteFileDocument = graphql(`\n  mutation SdkDeleteFile($workspaceID: ID!, $path: String!) {\n    deleteWorkspaceFile(input: { workspaceID: $workspaceID, path: $path }) {\n      ok\n    }\n  }\n`);\n\nexport const CreateDeploymentDocument = graphql(`\n  mutation SdkCreateDeployment($input: CreateDeploymentInput!) {\n    createDeployment(input: $input) {\n      deployment {\n        ...DeploymentFields\n      }\n    }\n  }\n`);\n\nexport const DeployWorkspaceDocument = graphql(`\n  mutation SdkDeployWorkspace($input: DeployWorkspaceInput!) {\n    deployWorkspace(input: $input) {\n      deployment {\n        ...DeploymentFields\n      }\n    }\n  }\n`);\n\nexport const GetDeploymentDocument = graphql(`\n  query SdkGetDeployment($id: ID!) {\n    deployment(id: $id) {\n      ...DeploymentFields\n    }\n  }\n`);\n\n/**\n * The poll document, deliberately narrow.\n *\n * Waiting can run for minutes at a few seconds per tick; selecting the full\n * fragment every time would cost the server (and an agent's rate limit) far\n * more than the four fields the state machine actually reads.\n */\nexport const PollDeploymentDocument = graphql(`\n  query SdkPollDeployment($id: ID!) {\n    deployment(id: $id) {\n      id\n      status\n      error\n      aliasHeld\n      url\n      previewUrl\n    }\n  }\n`);\n\nexport const GetDeploymentByAliasDocument = graphql(`\n  query SdkGetDeploymentByAlias($alias: String!) {\n    deploymentByAlias(alias: $alias) {\n      ...DeploymentFields\n    }\n  }\n`);\n\nexport const ListDeploymentsDocument = graphql(`\n  query SdkListDeployments($input: ListDeploymentsInput) {\n    deploymentsPage(input: $input) {\n      items {\n        ...DeploymentFields\n      }\n      total\n      limit\n      offset\n      hasMore\n      nextOffset\n    }\n  }\n`);\n\nexport const ListReleasesDocument = graphql(`\n  query SdkListReleases($alias: String!) {\n    deploymentReleases(alias: $alias) {\n      ...DeploymentFields\n    }\n  }\n`);\n\nexport const RollbackDocument = graphql(`\n  mutation SdkRollback(\n    $deploymentID: ID!\n    $expectedCurrentDeploymentID: ID!\n    $expectedCurrentAliasRevision: String!\n  ) {\n    rollbackDeployment(\n      input: {\n        deploymentID: $deploymentID\n        expectedCurrentDeploymentID: $expectedCurrentDeploymentID\n        expectedCurrentAliasRevision: $expectedCurrentAliasRevision\n      }\n    ) {\n      ...DeploymentFields\n    }\n  }\n`);\n\nexport const ServiceStatusDocument = graphql(`\n  query SdkServiceStatus($deploymentID: ID!) {\n    serviceStatus(deploymentID: $deploymentID) {\n      deploymentID\n      alias\n      serviceMode\n      running\n      health\n      vmID\n      inFlight\n      alwaysOn\n      memSizeMiB\n      startedAt\n      lastUsedAt\n      lastStoppedAt\n      restartCount\n      lastError\n    }\n  }\n`);\n\nexport const ServiceLogsDocument = graphql(`\n  query SdkServiceLogs($deploymentID: ID!, $tailBytes: Int) {\n    serviceLogs(deploymentID: $deploymentID, tailBytes: $tailBytes) {\n      deploymentID\n      stdout\n      stderr\n      truncated\n      stdoutBytes\n      stderrBytes\n      tailBytes\n    }\n  }\n`);\n\nexport const DeploymentEventsDocument = graphql(`\n  query SdkDeploymentEvents($deploymentID: ID!, $limit: Int) {\n    deploymentEvents(deploymentID: $deploymentID, limit: $limit) {\n      id\n      deploymentID\n      type\n      rawType\n      severity\n      message\n      vmID\n      createdAt\n    }\n  }\n`);\n\nexport const RestartServiceDocument = graphql(`\n  mutation SdkRestartService($deploymentID: ID!) {\n    restartService(input: { deploymentID: $deploymentID }) {\n      deploymentID\n      running\n      health\n      vmID\n      restartCount\n      lastError\n    }\n  }\n`);\n\nexport const StopServiceDocument = graphql(`\n  mutation SdkStopService($deploymentID: ID!) {\n    stopService(input: { deploymentID: $deploymentID }) {\n      deploymentID\n      running\n      health\n      vmID\n      restartCount\n      lastError\n    }\n  }\n`);\n\nexport const DeleteDeploymentDocument = graphql(`\n  mutation SdkDeleteDeployment($deploymentID: ID!) {\n    deleteDeployment(input: { deploymentID: $deploymentID }) {\n      ok\n    }\n  }\n`);\n\n/* -------------------------------------------------------------------------\n * Env & secrets\n *\n * Workspace-scoped values are SERVICE defaults for every app in the source;\n * app-scoped values override them for one alias. Both are snapshotted into a\n * release at deploy time, so a change only reaches a running app after a\n * redeploy — the workflow layer's doc comments repeat this where it matters.\n * ---------------------------------------------------------------------- */\n\nexport const SetWorkspaceEnvDocument = graphql(`\n  mutation SdkSetWorkspaceEnv($workspaceID: ID!, $name: String!, $value: String!) {\n    setWorkspaceEnv(input: { workspaceID: $workspaceID, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const SetWorkspaceSecretDocument = graphql(`\n  mutation SdkSetWorkspaceSecret($workspaceID: ID!, $name: String!, $value: String!) {\n    setWorkspaceSecret(input: { workspaceID: $workspaceID, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const DeleteWorkspaceEnvDocument = graphql(`\n  mutation SdkDeleteWorkspaceEnv($workspaceID: ID!, $name: String!) {\n    deleteWorkspaceEnv(input: { workspaceID: $workspaceID, name: $name }) {\n      ok\n    }\n  }\n`);\n\nexport const ListWorkspaceEnvDocument = graphql(`\n  query SdkListWorkspaceEnv($workspaceID: ID!) {\n    workspaceEnv(workspaceID: $workspaceID) {\n      name\n      value\n      secret\n      alias\n      inherited\n      masked\n      updatedAt\n    }\n  }\n`);\n\nexport const SetAppEnvDocument = graphql(`\n  mutation SdkSetAppEnv($workspaceID: ID!, $alias: String!, $name: String!, $value: String!) {\n    setAppEnv(input: { workspaceID: $workspaceID, alias: $alias, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const SetAppSecretDocument = graphql(`\n  mutation SdkSetAppSecret($workspaceID: ID!, $alias: String!, $name: String!, $value: String!) {\n    setAppSecret(input: { workspaceID: $workspaceID, alias: $alias, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const RemoveAppEnvDocument = graphql(`\n  mutation SdkRemoveAppEnv($workspaceID: ID!, $alias: String!, $name: String!) {\n    removeAppEnv(input: { workspaceID: $workspaceID, alias: $alias, name: $name }) {\n      ok\n    }\n  }\n`);\n\nexport const InheritAppEnvDocument = graphql(`\n  mutation SdkInheritAppEnv($workspaceID: ID!, $alias: String!, $name: String!) {\n    inheritAppEnv(input: { workspaceID: $workspaceID, alias: $alias, name: $name }) {\n      ok\n    }\n  }\n`);\n\nexport const ListAppEnvDocument = graphql(`\n  query SdkListAppEnv($workspaceID: ID!, $alias: String!) {\n    appEnv(workspaceID: $workspaceID, alias: $alias) {\n      name\n      value\n      secret\n      alias\n      inherited\n      masked\n      updatedAt\n    }\n  }\n`);\n\n/* -------------------------------------------------------------------------\n * Agent runs\n *\n * A run is the past-tense counterpart to a deployment: \"boot a fresh VM,\n * hand it a prompt, let a harness work, keep the transcript, record what it\n * cost, reap the VM\". `createRun` returns once the VM has started\n * (RUNNING) or FAILED with `error` when it could not boot — unlike\n * `createDeployment`, a FAILED run is a normal return value, not something\n * that only shows up later in a poll.\n * ---------------------------------------------------------------------- */\n\n/** Run fields the SDK returns everywhere. */\nexport const RunFieldsFragment = graphql(`\n  fragment RunFields on Run {\n    id\n    workspaceID\n    ownerId\n    status\n    rawStatus\n    command\n    harness\n    prompt\n    setup\n    skills\n    verify\n    approval\n    mode\n    access\n    alias\n    integrations {\n      kind\n      bindingID\n      env\n      skills\n      mcpServers {\n        name\n        transport\n        readOnly\n      }\n    }\n    parentRunID\n    depth\n    question {\n      id\n      text\n      options\n      askedAt\n    }\n    memoryMiB\n    maxSeconds\n    metadata\n    error\n    exitCode\n    result {\n      status\n      detail\n      text\n    }\n    verifyExitCode\n    vmID\n    transcriptAvailable\n    usage {\n      vmSeconds\n      memoryMiB\n      mibSeconds\n    }\n    createdAt\n    startedAt\n    settledAt\n  }\n`);\n\nexport const CreateRunDocument = graphql(`\n  mutation SdkCreateRun($input: CreateRunInput!) {\n    createRun(input: $input) {\n      ...RunFields\n    }\n  }\n`);\n\nexport const GetRunDocument = graphql(`\n  query SdkGetRun($id: ID!) {\n    run(id: $id) {\n      ...RunFields\n    }\n  }\n`);\n\n/**\n * The poll document, deliberately narrow — see {@link PollDeploymentDocument}\n * for why: this runs every few seconds for potentially up to an hour.\n */\nexport const PollRunDocument = graphql(`\n  query SdkPollRun($id: ID!) {\n    run(id: $id) {\n      id\n      status\n      error\n      exitCode\n    }\n  }\n`);\n\nexport const ListRunsDocument = graphql(`\n  query SdkListRuns($input: ListRunsInput) {\n    runs(input: $input) {\n      items {\n        ...RunFields\n      }\n      total\n      limit\n      offset\n      hasMore\n      nextOffset\n    }\n  }\n`);\n\nexport const CancelRunDocument = graphql(`\n  mutation SdkCancelRun($id: ID!) {\n    cancelRun(id: $id) {\n      ...RunFields\n    }\n  }\n`);\n\nexport const RunEventsDocument = graphql(`\n  query SdkRunEvents($runID: ID!, $limit: Int) {\n    runEvents(runID: $runID, limit: $limit) {\n      id\n      runID\n      type\n      severity\n      message\n      metadata\n      createdAt\n    }\n  }\n`);\n\n/** The live console tail of a RUNNING run. Empty with `running: false` once settled. */\nexport const RunConsoleDocument = graphql(`\n  query SdkRunConsole($id: ID!, $tailBytes: Int) {\n    runConsole(id: $id, tailBytes: $tailBytes) {\n      runID\n      running\n      text\n    }\n  }\n`);\n\n/** The bounded end of a finished run's stored transcript. */\nexport const RunTranscriptDocument = graphql(`\n  query SdkRunTranscript($id: ID!, $tailBytes: Int) {\n    runTranscript(id: $id, tailBytes: $tailBytes) {\n      runID\n      available\n      text\n      totalBytes\n      truncated\n    }\n  }\n`);\n\nexport const AnswerRunDocument = graphql(`\n  mutation SdkAnswerRun($id: ID!, $answer: String!) {\n    answerRun(id: $id, answer: $answer) {\n      ...RunFields\n    }\n  }\n`);\n\nexport const FollowUpRunDocument = graphql(`\n  mutation SdkFollowUpRun($input: FollowUpRunInput!) {\n    followUpRun(input: $input) {\n      ...RunFields\n    }\n  }\n`);\n\nexport const ListRunHarnessesDocument = graphql(`\n  query SdkRunHarnesses {\n    runHarnesses {\n      name\n      title\n      summary\n      requires\n    }\n  }\n`);\n"]}
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../src/operations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every GraphQL document the workflow layer sends.\n *\n * These are wrapped in `graphql(...)` so graphql-codegen validates them\n * against the vendored schema at codegen time and emits exact result/variable\n * types. A field that stops existing server-side turns into a compile error\n * here rather than a runtime surprise in an agent's script.\n *\n * The one document NOT defined here is the batched file write: it has a\n * variable number of aliased root fields, so it is assembled at runtime in\n * `unfazed.ts`. See the comment there.\n */\nimport { graphql } from \"./generated/gql.js\";\n\n/**\n * Deployment fields the SDK returns everywhere.\n *\n * `id` + `aliasRevision` + `aliasHeld` are the rollback compare-and-swap\n * triple; `previewUrl` is the immutable by-id URL you can verify BEFORE the\n * alias moves; `error` carries the build failure text when status is FAILED.\n */\nexport const DeploymentFieldsFragment = graphql(`\n  fragment DeploymentFields on Deployment {\n    id\n    workspaceID\n    kind\n    runtime\n    alias\n    serviceMode\n    healthPath\n    cronSchedule\n    cronPath\n    url\n    previewUrl\n    sshCommand\n    aliasHeld\n    aliasRevision\n    status\n    error\n    filesCount\n    sizeBytes\n    size\n    spaMode\n    gitRepo\n    gitCommit\n    createdAt\n  }\n`);\n\nexport const WhoamiDocument = graphql(`\n  query SdkWhoami {\n    whoami {\n      kind\n      userID\n      name\n      agentID\n      agentName\n      claimed\n      claimedBy\n      scopes\n      expiresAt\n      usage {\n        month\n        requests\n        limit\n      }\n      resources {\n        workspaces\n        workspaceLimit\n        services\n        serviceLimit\n      }\n    }\n  }\n`);\n\nexport const CreateWorkspaceDocument = graphql(`\n  mutation SdkCreateWorkspace($name: String!) {\n    createWorkspace(input: { name: $name }) {\n      workspace {\n        id\n        name\n        ownerId\n        projectId\n        createdAt\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const ListWorkspacesDocument = graphql(`\n  query SdkListWorkspaces {\n    workspaces {\n      id\n      name\n      ownerId\n      projectId\n      createdAt\n      updatedAt\n    }\n  }\n`);\n\n/**\n * Deleting a workspace, with the deployment cascade made explicit.\n *\n * Without `withDeployments` the server REFUSES while the workspace has any\n * deployment record at all — FAILED ones included — with `workspace %q still\n * has deployments; delete them first`. With it, the delete takes down every\n * app the workspace serves, so `confirmAliases` must name exactly those apps\n * (`Workspace.liveApps`); a missing or extra alias refuses the delete, deletes\n * nothing, and the error lists the live apps. The SDK always sends the flag\n * and never fills in the aliases: the caller names what goes.\n */\nexport const DeleteWorkspaceDocument = graphql(`\n  mutation SdkDeleteWorkspace(\n    $workspaceID: ID!\n    $withDeployments: Boolean\n    $confirmAliases: [String!]\n  ) {\n    deleteWorkspace(\n      input: {\n        workspaceID: $workspaceID\n        withDeployments: $withDeployments\n        confirmAliases: $confirmAliases\n      }\n    ) {\n      ok\n    }\n  }\n`);\n\n/**\n * The apps a workspace serves right now: what `deleteWorkspace` with\n * `withDeployments` takes offline, and exactly the list its `confirmAliases`\n * must name. `workspace` is null when the id is absent or not the caller's.\n */\nexport const WorkspaceLiveAppsDocument = graphql(`\n  query SdkWorkspaceLiveApps($id: ID!) {\n    workspace(id: $id) {\n      id\n      liveApps {\n        alias\n        deploymentID\n        domains\n      }\n    }\n  }\n`);\n\n/**\n * Deleting ONE app of a workspace: every deployment of the alias there, its\n * App State, app-scoped env and secrets, and integration bindings. The\n * workspace, its files and its other apps keep serving.\n */\nexport const DeleteAppDocument = graphql(`\n  mutation SdkDeleteApp($workspaceID: ID!, $alias: String!) {\n    deleteApp(input: { workspaceID: $workspaceID, alias: $alias }) {\n      ok\n      alias\n      deployments\n      domains\n      envEntries\n      skippedOnSync\n      otherApps\n    }\n  }\n`);\n\nexport const WriteTextFileDocument = graphql(`\n  mutation SdkWriteTextFile($workspaceID: ID!, $path: String!, $text: String!) {\n    writeWorkspaceTextFile(input: { workspaceID: $workspaceID, path: $path, text: $text }) {\n      file {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const WriteBase64FileDocument = graphql(`\n  mutation SdkWriteBase64File($workspaceID: ID!, $path: String!, $contentBase64: String!) {\n    writeWorkspaceBase64File(\n      input: { workspaceID: $workspaceID, path: $path, contentBase64: $contentBase64 }\n    ) {\n      file {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n    }\n  }\n`);\n\n/** The commit a file write made on an app with platform git (MCP's `commit`). */\nexport const FileCommitFieldsFragment = graphql(`\n  fragment FileCommitFields on FileCommit {\n    sha\n    branch\n    message\n    committed\n    waiting\n    waitingCount\n    deploys\n    conflicts\n    writeSHA\n    paused\n  }\n`);\n\n/**\n * The batch write (MCP `write_workspace_files`): every file in ONE request\n * and, on an app with platform git, ONE commit for the whole call.\n */\nexport const WriteFilesDocument = graphql(`\n  mutation SdkWriteFiles(\n    $workspaceID: ID!\n    $files: [WorkspaceFileWriteInput!]!\n    $commitMessage: String\n  ) {\n    writeWorkspaceFiles(\n      input: { workspaceID: $workspaceID, files: $files, commitMessage: $commitMessage }\n    ) {\n      workspaceID\n      written\n      failed\n      totalBytes\n      files {\n        path\n        ok\n        error\n        file {\n          path\n          sizeBytes\n          size\n          sha256\n          updatedAt\n        }\n      }\n      commit {\n        ...FileCommitFields\n      }\n    }\n  }\n`);\n\n/** One page of an app's platform git history, newest first (MCP `list_commits`). */\nexport const AppCommitsDocument = graphql(`\n  query SdkAppCommits($workspaceID: ID!, $limit: Int, $before: String) {\n    appCommits(workspaceID: $workspaceID, limit: $limit, before: $before) {\n      branch\n      head\n      nextBefore\n      autoDeploy\n      waitingCommits\n      waitingSince\n      commits {\n        sha\n        message\n        authorName\n        authorEmail\n        authoredAt\n        filesChanged\n        deployedTo\n      }\n      deployed {\n        alias\n        sha\n        deploymentID\n      }\n    }\n  }\n`);\n\n/** Only what `waitForCommit` reads: whether writes still wait, and the head. */\nexport const AppCommitsWaitingDocument = graphql(`\n  query SdkAppCommitsWaiting($workspaceID: ID!) {\n    appCommits(workspaceID: $workspaceID, limit: 1) {\n      branch\n      head\n      waitingCommits\n      waitingSince\n    }\n  }\n`);\n\n/**\n * The app's git link as the last import left it: what `restoreVersion` waits\n * on, since the deploy a restore queues is an import of the branch head.\n */\nexport const WorkspaceGitSourceDocument = graphql(`\n  query SdkWorkspaceGitSource($id: ID!) {\n    workspace(id: $id) {\n      id\n      gitSource {\n        branch\n        autoDeploy\n        deployAlias\n        lastImportedCommit\n        lastImportedAt\n        lastImportStatus\n        lastImportError\n      }\n    }\n  }\n`);\n\n/** One commit with its diff (MCP `get_commit`). */\nexport const AppCommitDocument = graphql(`\n  query SdkAppCommit($workspaceID: ID!, $sha: String!) {\n    appCommit(workspaceID: $workspaceID, sha: $sha) {\n      commit {\n        sha\n        message\n        authorName\n        authorEmail\n        authoredAt\n        filesChanged\n        deployedTo\n      }\n      files {\n        path\n        status\n      }\n      patch\n      truncated\n      additions\n      deletions\n    }\n  }\n`);\n\n/** Give the app back an earlier commit's files (MCP `restore_version`). */\nexport const RestoreVersionDocument = graphql(`\n  mutation SdkRestoreVersion(\n    $workspaceID: ID!\n    $sha: String!\n    $expectedHead: String\n    $message: String\n  ) {\n    restoreAppVersion(\n      input: { workspaceID: $workspaceID, sha: $sha, expectedHead: $expectedHead, message: $message }\n    ) {\n      sha\n      committed\n      deploys\n      message\n      branch\n      deployAlias\n      restoredFrom\n      parent\n    }\n  }\n`);\n\n/** A service app's error group, as MCP `list_errors` shows it. */\nexport const AppErrorGroupFieldsFragment = graphql(`\n  fragment AppErrorGroupFields on AppErrorGroup {\n    id\n    title\n    type\n    culprit\n    level\n    status\n    count\n    storedEvents\n    firstSeen\n    lastSeen\n    firstDeploymentID\n    firstGitCommit\n    lastDeploymentID\n    lastGitCommit\n    resolvedInDeploymentID\n    resolvedAt\n    mutedAt\n    regressedAt\n  }\n`);\n\nexport const AppErrorsDocument = graphql(`\n  query SdkAppErrors(\n    $workspaceID: ID!\n    $alias: String!\n    $status: String\n    $limit: Int\n    $cursor: String\n  ) {\n    appErrors(\n      workspaceID: $workspaceID\n      alias: $alias\n      status: $status\n      limit: $limit\n      cursor: $cursor\n    ) {\n      groups {\n        ...AppErrorGroupFields\n      }\n      nextCursor\n      note\n    }\n  }\n`);\n\nexport const AppErrorGroupDocument = graphql(`\n  query SdkAppErrorGroup($workspaceID: ID!, $alias: String!, $groupID: ID!) {\n    appErrorGroup(workspaceID: $workspaceID, alias: $alias, groupID: $groupID) {\n      group {\n        ...AppErrorGroupFields\n      }\n      latestEvent\n      firstEvent {\n        eventID\n        at\n        deploymentID\n        level\n      }\n      recentEvents {\n        eventID\n        at\n        deploymentID\n        level\n      }\n      deployments {\n        deploymentID\n        gitCommit\n        current\n        count\n        firstSeen\n        lastSeen\n      }\n      fatal\n      vmID\n    }\n  }\n`);\n\nexport const ResolveErrorGroupDocument = graphql(`\n  mutation SdkResolveErrorGroup($input: AppErrorGroupInput!) {\n    resolveAppErrorGroup(input: $input) {\n      ...AppErrorGroupFields\n    }\n  }\n`);\n\nexport const MuteErrorGroupDocument = graphql(`\n  mutation SdkMuteErrorGroup($input: AppErrorGroupInput!) {\n    muteAppErrorGroup(input: $input) {\n      ...AppErrorGroupFields\n    }\n  }\n`);\n\nexport const ReopenErrorGroupDocument = graphql(`\n  mutation SdkReopenErrorGroup($input: AppErrorGroupInput!) {\n    reopenAppErrorGroup(input: $input) {\n      ...AppErrorGroupFields\n    }\n  }\n`);\n\n/** The event types pollEvents/waitForEvents read (MCP `list_event_types`). */\nexport const EventTypesDocument = graphql(`\n  query SdkEventTypes {\n    platformEventTypes {\n      name\n      description\n      delivery\n      inputSchema\n      payloadSchema\n    }\n  }\n`);\n\n/** MCP `poll_events`: the same feed, cursors and filters. */\nexport const PollEventsDocument = graphql(`\n  query SdkPollEvents($input: PlatformEventsInput) {\n    pollEvents(input: $input) {\n      cursor\n      truncated\n      hasMore\n      nextPollMs\n      timedOut\n      events {\n        eventID\n        name\n        timestamp\n        data\n      }\n    }\n  }\n`);\n\n/** MCP `wait_for_events`: pollEvents that blocks server-side (at most 50 s). */\nexport const WaitForEventsDocument = graphql(`\n  query SdkWaitForEvents($input: PlatformEventsInput, $timeoutSeconds: Int) {\n    waitForEvents(input: $input, timeoutSeconds: $timeoutSeconds) {\n      cursor\n      truncated\n      hasMore\n      nextPollMs\n      timedOut\n      events {\n        eventID\n        name\n        timestamp\n        data\n      }\n    }\n  }\n`);\n\nexport const ListFilesDocument = graphql(`\n  query SdkListFiles($input: ListWorkspaceFilesInput!) {\n    workspaceFilesPage(input: $input) {\n      items {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n      total\n      limit\n      offset\n      hasMore\n      nextOffset\n    }\n  }\n`);\n\nexport const ReadFileDocument = graphql(`\n  query SdkReadFile($input: ReadWorkspaceFileInput!) {\n    readWorkspaceFile(input: $input) {\n      text\n      offset\n      limit\n      totalBytes\n      truncated\n      nextOffset\n      file {\n        path\n        sizeBytes\n        size\n        sha256\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const DeleteFileDocument = graphql(`\n  mutation SdkDeleteFile($workspaceID: ID!, $path: String!) {\n    deleteWorkspaceFile(input: { workspaceID: $workspaceID, path: $path }) {\n      ok\n    }\n  }\n`);\n\nexport const CreateDeploymentDocument = graphql(`\n  mutation SdkCreateDeployment($input: CreateDeploymentInput!) {\n    createDeployment(input: $input) {\n      deployment {\n        ...DeploymentFields\n      }\n    }\n  }\n`);\n\nexport const DeployWorkspaceDocument = graphql(`\n  mutation SdkDeployWorkspace($input: DeployWorkspaceInput!) {\n    deployWorkspace(input: $input) {\n      deployment {\n        ...DeploymentFields\n      }\n    }\n  }\n`);\n\nexport const GetDeploymentDocument = graphql(`\n  query SdkGetDeployment($id: ID!) {\n    deployment(id: $id) {\n      ...DeploymentFields\n    }\n  }\n`);\n\n/**\n * The poll document, deliberately narrow.\n *\n * Waiting can run for minutes at a few seconds per tick; selecting the full\n * fragment every time would cost the server (and an agent's rate limit) far\n * more than the four fields the state machine actually reads.\n */\nexport const PollDeploymentDocument = graphql(`\n  query SdkPollDeployment($id: ID!) {\n    deployment(id: $id) {\n      id\n      status\n      error\n      aliasHeld\n      url\n      previewUrl\n    }\n  }\n`);\n\nexport const GetDeploymentByAliasDocument = graphql(`\n  query SdkGetDeploymentByAlias($alias: String!) {\n    deploymentByAlias(alias: $alias) {\n      ...DeploymentFields\n    }\n  }\n`);\n\nexport const ListDeploymentsDocument = graphql(`\n  query SdkListDeployments($input: ListDeploymentsInput) {\n    deploymentsPage(input: $input) {\n      items {\n        ...DeploymentFields\n      }\n      total\n      limit\n      offset\n      hasMore\n      nextOffset\n    }\n  }\n`);\n\nexport const ListReleasesDocument = graphql(`\n  query SdkListReleases($alias: String!) {\n    deploymentReleases(alias: $alias) {\n      ...DeploymentFields\n    }\n  }\n`);\n\nexport const RollbackDocument = graphql(`\n  mutation SdkRollback(\n    $deploymentID: ID!\n    $expectedCurrentDeploymentID: ID!\n    $expectedCurrentAliasRevision: String!\n  ) {\n    rollbackDeployment(\n      input: {\n        deploymentID: $deploymentID\n        expectedCurrentDeploymentID: $expectedCurrentDeploymentID\n        expectedCurrentAliasRevision: $expectedCurrentAliasRevision\n      }\n    ) {\n      ...DeploymentFields\n    }\n  }\n`);\n\nexport const ServiceStatusDocument = graphql(`\n  query SdkServiceStatus($deploymentID: ID!) {\n    serviceStatus(deploymentID: $deploymentID) {\n      deploymentID\n      alias\n      serviceMode\n      running\n      health\n      vmID\n      inFlight\n      alwaysOn\n      memSizeMiB\n      startedAt\n      lastUsedAt\n      lastStoppedAt\n      restartCount\n      lastError\n    }\n  }\n`);\n\nexport const ServiceLogsDocument = graphql(`\n  query SdkServiceLogs($deploymentID: ID!, $tailBytes: Int) {\n    serviceLogs(deploymentID: $deploymentID, tailBytes: $tailBytes) {\n      deploymentID\n      stdout\n      stderr\n      truncated\n      stdoutBytes\n      stderrBytes\n      tailBytes\n    }\n  }\n`);\n\n/**\n * Deployment events with their metadata: the timing events\n * (`deployment.phases`, `deployment.build_finished`) carry their phases there\n * as `*_ms` fields, which `parseDeploymentTimings` turns into numbers.\n */\nexport const DeploymentEventsDocument = graphql(`\n  query SdkDeploymentEvents($deploymentID: ID!, $limit: Int) {\n    deploymentEvents(deploymentID: $deploymentID, limit: $limit) {\n      id\n      deploymentID\n      type\n      rawType\n      severity\n      message\n      vmID\n      metadata\n      createdAt\n    }\n  }\n`);\n\n/**\n * The server-side wait (MCP `wait_for_deployment`): the control plane blocks\n * until the deployment leaves BUILDING — woken by the deploy pipeline itself,\n * not a timer — or its budget (at most 50 s) runs out. One round trip after\n * READY instead of a poll interval, and the full deployment in the answer.\n */\nexport const WaitForDeploymentDocument = graphql(`\n  query SdkWaitForDeployment($id: ID!, $timeoutSeconds: Int) {\n    waitForDeployment(id: $id, timeoutSeconds: $timeoutSeconds) {\n      timedOut\n      waitedMs\n      placement\n      deployment {\n        ...DeploymentFields\n      }\n    }\n  }\n`);\n\nexport const RestartServiceDocument = graphql(`\n  mutation SdkRestartService($deploymentID: ID!) {\n    restartService(input: { deploymentID: $deploymentID }) {\n      deploymentID\n      running\n      health\n      vmID\n      restartCount\n      lastError\n    }\n  }\n`);\n\nexport const StopServiceDocument = graphql(`\n  mutation SdkStopService($deploymentID: ID!) {\n    stopService(input: { deploymentID: $deploymentID }) {\n      deploymentID\n      running\n      health\n      vmID\n      restartCount\n      lastError\n    }\n  }\n`);\n\nexport const DeleteDeploymentDocument = graphql(`\n  mutation SdkDeleteDeployment($deploymentID: ID!) {\n    deleteDeployment(input: { deploymentID: $deploymentID }) {\n      ok\n    }\n  }\n`);\n\n/* -------------------------------------------------------------------------\n * Env & secrets\n *\n * Workspace-scoped values are SERVICE defaults for every app in the source;\n * app-scoped values override them for one alias. Both are snapshotted into a\n * release at deploy time, so a change only reaches a running app after a\n * redeploy — the workflow layer's doc comments repeat this where it matters.\n * ---------------------------------------------------------------------- */\n\nexport const SetWorkspaceEnvDocument = graphql(`\n  mutation SdkSetWorkspaceEnv($workspaceID: ID!, $name: String!, $value: String!) {\n    setWorkspaceEnv(input: { workspaceID: $workspaceID, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const SetWorkspaceSecretDocument = graphql(`\n  mutation SdkSetWorkspaceSecret($workspaceID: ID!, $name: String!, $value: String!) {\n    setWorkspaceSecret(input: { workspaceID: $workspaceID, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const DeleteWorkspaceEnvDocument = graphql(`\n  mutation SdkDeleteWorkspaceEnv($workspaceID: ID!, $name: String!) {\n    deleteWorkspaceEnv(input: { workspaceID: $workspaceID, name: $name }) {\n      ok\n    }\n  }\n`);\n\nexport const ListWorkspaceEnvDocument = graphql(`\n  query SdkListWorkspaceEnv($workspaceID: ID!) {\n    workspaceEnv(workspaceID: $workspaceID) {\n      name\n      value\n      secret\n      alias\n      inherited\n      masked\n      updatedAt\n    }\n  }\n`);\n\nexport const SetAppEnvDocument = graphql(`\n  mutation SdkSetAppEnv($workspaceID: ID!, $alias: String!, $name: String!, $value: String!) {\n    setAppEnv(input: { workspaceID: $workspaceID, alias: $alias, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const SetAppSecretDocument = graphql(`\n  mutation SdkSetAppSecret($workspaceID: ID!, $alias: String!, $name: String!, $value: String!) {\n    setAppSecret(input: { workspaceID: $workspaceID, alias: $alias, name: $name, value: $value }) {\n      env {\n        name\n        value\n        secret\n        alias\n        inherited\n        masked\n        updatedAt\n      }\n    }\n  }\n`);\n\nexport const RemoveAppEnvDocument = graphql(`\n  mutation SdkRemoveAppEnv($workspaceID: ID!, $alias: String!, $name: String!) {\n    removeAppEnv(input: { workspaceID: $workspaceID, alias: $alias, name: $name }) {\n      ok\n    }\n  }\n`);\n\nexport const InheritAppEnvDocument = graphql(`\n  mutation SdkInheritAppEnv($workspaceID: ID!, $alias: String!, $name: String!) {\n    inheritAppEnv(input: { workspaceID: $workspaceID, alias: $alias, name: $name }) {\n      ok\n    }\n  }\n`);\n\nexport const ListAppEnvDocument = graphql(`\n  query SdkListAppEnv($workspaceID: ID!, $alias: String!) {\n    appEnv(workspaceID: $workspaceID, alias: $alias) {\n      name\n      value\n      secret\n      alias\n      inherited\n      masked\n      updatedAt\n    }\n  }\n`);\n\n/* -------------------------------------------------------------------------\n * Agent runs\n *\n * A run is the past-tense counterpart to a deployment: \"boot a fresh VM,\n * hand it a prompt, let a harness work, keep the transcript, record what it\n * cost, reap the VM\". `createRun` returns once the VM has started\n * (RUNNING) or FAILED with `error` when it could not boot — unlike\n * `createDeployment`, a FAILED run is a normal return value, not something\n * that only shows up later in a poll.\n * ---------------------------------------------------------------------- */\n\n/** Run fields the SDK returns everywhere. */\nexport const RunFieldsFragment = graphql(`\n  fragment RunFields on Run {\n    id\n    workspaceID\n    ownerId\n    status\n    rawStatus\n    command\n    harness\n    prompt\n    setup\n    skills\n    verify\n    approval\n    mode\n    access\n    alias\n    integrations {\n      kind\n      bindingID\n      env\n      skills\n      mcpServers {\n        name\n        transport\n        readOnly\n      }\n    }\n    parentRunID\n    depth\n    question {\n      id\n      text\n      options\n      askedAt\n    }\n    memoryMiB\n    maxSeconds\n    metadata\n    error\n    exitCode\n    result {\n      status\n      detail\n      text\n    }\n    verifyExitCode\n    vmID\n    transcriptAvailable\n    usage {\n      vmSeconds\n      memoryMiB\n      mibSeconds\n    }\n    createdAt\n    startedAt\n    settledAt\n  }\n`);\n\nexport const CreateRunDocument = graphql(`\n  mutation SdkCreateRun($input: CreateRunInput!) {\n    createRun(input: $input) {\n      ...RunFields\n    }\n  }\n`);\n\nexport const GetRunDocument = graphql(`\n  query SdkGetRun($id: ID!) {\n    run(id: $id) {\n      ...RunFields\n    }\n  }\n`);\n\n/**\n * The poll document, deliberately narrow — see {@link PollDeploymentDocument}\n * for why: this runs every few seconds for potentially up to an hour.\n */\nexport const PollRunDocument = graphql(`\n  query SdkPollRun($id: ID!) {\n    run(id: $id) {\n      id\n      status\n      error\n      exitCode\n    }\n  }\n`);\n\nexport const ListRunsDocument = graphql(`\n  query SdkListRuns($input: ListRunsInput) {\n    runs(input: $input) {\n      items {\n        ...RunFields\n      }\n      total\n      limit\n      offset\n      hasMore\n      nextOffset\n    }\n  }\n`);\n\nexport const CancelRunDocument = graphql(`\n  mutation SdkCancelRun($id: ID!) {\n    cancelRun(id: $id) {\n      ...RunFields\n    }\n  }\n`);\n\nexport const RunEventsDocument = graphql(`\n  query SdkRunEvents($runID: ID!, $limit: Int) {\n    runEvents(runID: $runID, limit: $limit) {\n      id\n      runID\n      type\n      severity\n      message\n      metadata\n      createdAt\n    }\n  }\n`);\n\n/** The live console tail of a RUNNING run. Empty with `running: false` once settled. */\nexport const RunConsoleDocument = graphql(`\n  query SdkRunConsole($id: ID!, $tailBytes: Int) {\n    runConsole(id: $id, tailBytes: $tailBytes) {\n      runID\n      running\n      text\n    }\n  }\n`);\n\n/** The bounded end of a finished run's stored transcript. */\nexport const RunTranscriptDocument = graphql(`\n  query SdkRunTranscript($id: ID!, $tailBytes: Int) {\n    runTranscript(id: $id, tailBytes: $tailBytes) {\n      runID\n      available\n      text\n      totalBytes\n      truncated\n    }\n  }\n`);\n\nexport const AnswerRunDocument = graphql(`\n  mutation SdkAnswerRun($id: ID!, $answer: String!) {\n    answerRun(id: $id, answer: $answer) {\n      ...RunFields\n    }\n  }\n`);\n\nexport const FollowUpRunDocument = graphql(`\n  mutation SdkFollowUpRun($input: FollowUpRunInput!) {\n    followUpRun(input: $input) {\n      ...RunFields\n    }\n  }\n`);\n\nexport const ListRunHarnessesDocument = graphql(`\n  query SdkRunHarnesses {\n    runHarnesses {\n      name\n      title\n      summary\n      requires\n    }\n  }\n`);\n"]}

package/dist/reference.d.ts

@@ -0,0 +1,18 @@
+import { REFERENCE } from "./reference.generated.js";
+export { REFERENCE };
+/**
+ * The SDK's reference, for a script (or a model) that needs a signature:
+ * every method of {@link Unfazed} with its parameters, result and an
+ * example, in one page (REFERENCE.md). It describes THIS version, the one
+ * the script imported (`VERSION`): exactly what `help()` should answer.
+ *
+ * ```ts
+ * import { help } from "unfazed";
+ * export default () => help("writeFiles");   // run_script returns the entry
+ * ```
+ *
+ * `help()` is the whole page; `help(topic)` the entries whose heading names
+ * it (a method like `"restoreVersion"`, or a section like `"Events"`), or the
+ * list of methods when nothing matches.
+ */
+export declare function help(topic?: string): string;

package/dist/reference.generated.d.ts

@@ -0,0 +1,2 @@
+/** The SDK's reference: every method with its signature (REFERENCE.md). */
+export declare const REFERENCE: string;

package/dist/reference.generated.js

@@ -0,0 +1,5 @@
+// GENERATED by scripts/embed-reference.ts from REFERENCE.md. Do not edit:
+// change REFERENCE.md and run `bun run embed-reference`.
+/** The SDK's reference: every method with its signature (REFERENCE.md). */
+export const REFERENCE = "# unfazed SDK reference\n\nEvery method of `Unfazed`, with its signature, in one page. In a script:\n`import { Unfazed, help } from \"unfazed\"; const unfazed = new Unfazed();`\n(run_script injects the credential; elsewhere `UNFZ_API_TOKEN` or\n`npx unfazed login`). `help()` returns this page; `help(\"writeFiles\")` one\nentry. Methods are async and throw an `UnfazedError` subclass on failure.\nEvery method takes an optional last `options` with `signal` (and, for single\nrequests, `timeoutMs`). The names follow the MCP tools: `listCommits` is\n`list_commits`, `waitForEvents` is `wait_for_events`.\n\n```ts\nimport { Unfazed } from \"unfazed\";\n\nexport default async () => {\n  const unfazed = new Unfazed();\n  const ws = await unfazed.ensureWorkspace(\"hello\");\n  const wrote = await unfazed.writeFiles(ws.id, {\n    \"server.ts\": `export default { fetch: () => new Response(\"hi\") }`,\n    \"package.json\": JSON.stringify({ name: \"hello\" }),\n  }, { commitMessage: \"First version\" });                // ONE request, ONE commit\n  const app = await unfazed.deployService({ workspaceId: ws.id, alias: \"hello\", wait: true });\n  return { url: app.url, commit: wrote.commit?.sha, timings: app.timings };\n};\n```\n\n## Saved, committed, deployed\n\nA file write has three states. **Saved**: the call returned; the app's\nfiles have it and the next deploy uses it. **Committed**: on an app with\nplatform git, `commit.committed && !commit.waiting`; it is in `listCommits`.\n**Deployed**: a deploy of those files went READY (`deployService({ wait:\ntrue })`). A write never deploys by itself, except when `commit.deploys` is\ntrue (the branch head is imported like a push).\n\n`commit.waiting: true` means saved, with the commit queued for the git\nserver: it lands in order, `sha` is null until then, nothing to retry.\n`waitForCommit` (or `writeFiles(…, { waitForCommit: true })`) resolves once\nit landed.\n\n## Workspaces\n\n### `createWorkspace(name: string): Promise<Workspace>`\nA new workspace: files, env, deployments. Names are unique per owner,\ncase-insensitively; prefer `ensureWorkspace` in re-runnable scripts.\n\n### `ensureWorkspace(name: string): Promise<Workspace>`\nThe workspace named `name`, created only when missing. Safe to re-run.\n\n### `listWorkspaces(): Promise<Workspace[]>`\n\n### `liveApps(workspaceId: string): Promise<LiveApp[]>`\nThe apps the workspace serves now: `{ alias, deploymentID, domains }`.\n\n### `deleteWorkspace(workspaceId: string, options?: { withDeployments?: true, confirmAliases: string[], ignoreNotFound?: boolean }): Promise<boolean>`\nDeletes it; with `withDeployments`, every app it serves, which\n`confirmAliases` must name exactly (`liveApps`). Kept 30 days for support.\n\n### `deleteApp(app: { workspaceId, alias }, options?: { ignoreNotFound?: boolean }): Promise<DeleteAppResult>`\nDeletes one app (every deployment of the alias, its App State, env and\nbindings); the workspace and its other apps stay.\n\n### `whoami(): Promise<Whoami>`\nWho the token is, its scopes, usage and limits.\n\n## Files\n\n### `writeFiles(workspaceId: string, files: Record<string, string | { text } | { base64 } | { bytes }>, options?: { commitMessage?: string, waitForCommit?: boolean | WaitOptions, allowPartial?: boolean }): Promise<WriteFilesResult>`\nWrites every file in ONE request, which is ONE commit on an app with\nplatform git (MCP `write_workspace_files`). Result: `{ files: [{ path, ok,\nerror, file }], written, failed, totalBytes, commit, commits, landed? }`;\n`commit` is `{ sha, branch, message, committed, waiting, waitingCount,\ndeploys, conflicts, writeSHA, paused }` or null without platform git. Not\ntransactional: when a file fails it throws `UnfazedWriteError` (`.result`,\n`.failed`) unless `allowPartial`. Up to 100 files and 32 MiB per request; a\nbigger map is several requests, each a commit.\n\n```ts\nconst out = await unfazed.writeFiles(ws.id, { \"a.ts\": a, \"logo.png\": { bytes } }, { commitMessage: \"Logo\" });\nif (out.commit?.conflicts.length) console.log(\"a push changed\", out.commit.conflicts, \"mine:\", out.commit.writeSHA);\n```\n\n### `writeFile(workspaceId: string, path: string, text: string, options?: { commitMessage?, waitForCommit? }): Promise<WorkspaceFile & { commit }>`\nOne text file: `writeFiles` with one entry.\n\n### `writeBinaryFile(workspaceId: string, path: string, content: Uint8Array | ArrayBuffer | { base64: string }, options?): Promise<WorkspaceFile & { commit }>`\n\n### `waitForCommit(workspaceId: string, waitOptions?: WaitOptions): Promise<{ branch, head, waitedMs }>`\nResolves once no write of the app waits for its commit; `head` then has\nevery earlier write. Immediate (`head: null`) without platform git. Default\ntimeout 2 minutes (`UnfazedTimeoutError`; the writes stay saved).\n\n### `readFile(workspaceId: string, path: string, input?: { offset?, limit? }): Promise<{ text, totalBytes, truncated, nextOffset, file } | null>`\n\n### `listFiles(workspaceId: string, input?: { limit?, offset?, order? }): Promise<WorkspaceFilePage>`\n\n### `deleteFile(workspaceId: string, path: string): Promise<boolean>`\n`false` when there was nothing to delete.\n\n## Deploys\n\n### `deployService(options: { workspaceId, alias?, wait?, waitOptions?, timings?, runtime?, serviceMode?, healthPath?, cronSchedule?, cronPath? }): Promise<DeployResult>`\nBuilds and deploys the workspace as an HTTP service (`server.ts` default\nexport, or `unfazed.json`). Returns BUILDING at once; with `wait: true`,\nresolves READY or throws `UnfazedDeployError` (`reason` FAILED with the\nbuild error, or TIMEOUT; default 10 minutes). Every call is a new release;\nthe same `alias` redeploys that app.\n\nWith `wait: true` the result has `timings`:\n`{ client: { createMs, waitMs, totalMs, waitRequests, waitMode },\nplatform: { totalMs, buildMs, promoteMs, phases, buildMode,\nartifactTransport, buildMemoryMiB } }`, both in milliseconds. `platform` is\nwhat the platform measured (created to READY); `client` is what you waited.\nThe wait is server-side, so the two differ by about one round trip.\n\n```ts\nconst app = await unfazed.deployService({ workspaceId: ws.id, alias: \"api\", wait: true });\napp.timings?.platform?.phases;   // { vm_install: 900, vm_build: 2600, admission: 40, … }\n```\n\n### `deployStatic(options: { workspaceId, alias?, wait?, spaMode? }): Promise<DeployResult>`\n\n### `deployBox(options: { workspaceId, alias, wait?, resources?: { memMiB?, vcpus?, diskGiB? } }): Promise<DeployResult>`\nA persistent Linux VM over SSH (`sshCommand`). Always pass `alias`.\n\n### `deploy(input: CreateDeploymentInput, options?: { wait?, waitOptions?, timings? }): Promise<DeployResult>`\nAny `createDeployment` input.\n\n### `waitForDeployment(deploymentId: string, waitOptions?: WaitOptions): Promise<Deployment>`\nWaits server-side (MCP `wait_for_deployment`: one request per 45 s at most,\nanswered when the status changes) until READY; throws `UnfazedDeployError`\non FAILED or timeout. A new app's landing on its server is waited for too.\n`waitOptions: { timeoutMs?, signal?, mode?: \"server\" | \"poll\" }`. The\nplatform holds at most 16 waits of one account at once; past that a wait\npolls instead.\n\n### `getDeployment(deploymentId: string): Promise<Deployment | null>`\n\n### `getDeploymentByAlias(alias: string): Promise<Deployment | null>`\n\n### `listDeployments(input?: { workspaceID?, alias?, kind?, limit?, offset? }): Promise<DeploymentPage>`\nNewest first.\n\n### `listReleases(alias: string): Promise<Deployment[]>`\nThe alias's history; `aliasHeld` marks the live one.\n\n### `rollback(options: { alias, to?, expectedCurrentId?, retries? }): Promise<Deployment>`\nPoints the alias back at a prior READY release (default: the one before\nthe live one). A bare `rollback({ alias })` toggles; pin `to` in anything\nre-runnable.\n\n### `deleteDeployment(deploymentId: string, options?: { ignoreNotFound? }): Promise<boolean>`\n\n## Runtime, logs, events, timings\n\n### `getStatus(deploymentId: string): Promise<ServiceStatus>`\n`{ running, health, inFlight, restartCount, memSizeMiB, lastError, … }`.\n\n### `getLogs(deploymentId: string, input?: { tailBytes? }): Promise<{ stdout, stderr, truncated, … }>`\nFilter in the script: `logs.stderr.split(\"\\n\").filter((l) => l.includes(\"ERROR\"))`.\n\n### `getEvents(deploymentId: string, limit?: number): Promise<DeploymentEvent[]>`\nThe latest `limit` (default 20) lifecycle events, oldest first: `{ type,\ntypeEnum, severity, message, vmID, metadata, createdAt }`. `type` is the\nevent's own name, as MCP reports it: `\"deployment.build_finished\"`,\n`\"deployment.phases\"`, `\"service.vm_started\"`. `typeEnum` is the GraphQL\nenum (`UNKNOWN` for names it lacks); match on `type`.\n\n### `getDeploymentTimings(deploymentId: string): Promise<PlatformTimings | null>`\nA deploy's measured phases (ms) from its timing events: `{ totalMs,\nbuildMs, promoteMs, phases, buildMode, artifactTransport, buildMemoryMiB }`.\n`parseDeploymentTimings(events)` does the same for events you already read.\n\n### `restartService(deploymentId: string)` / `stopService(deploymentId: string)`\n\n## Env and secrets\n\nSnapshotted into a release at deploy time: redeploy the alias to apply.\n\n### `setEnv(workspaceId, name, value)` / `setSecret(workspaceId, name, value)`: `Promise<EnvVar>`\nWorkspace defaults. A name is plain or secret, never both.\n\n### `setEnvMany(workspaceId: string, vars: Record<string, string>, options?: { secret?: boolean }): Promise<EnvVar[]>`\n\n### `deleteEnv(workspaceId, name): Promise<boolean>` / `listEnv(workspaceId): Promise<EnvVar[]>`\n\n### `setAppEnv(workspaceId, alias, name, value)` / `setAppSecret(workspaceId, alias, name, value)`: `Promise<EnvVar>`\nOne app's override.\n\n### `removeAppEnv(workspaceId, alias, name): Promise<boolean>`\nBlocks the name for the app (a mask). `inheritAppEnv` clears it.\n\n### `inheritAppEnv(workspaceId, alias, name): Promise<boolean>` / `listAppEnv(workspaceId, alias): Promise<EnvVar[]>`\n\n## History (platform git)\n\n### `listCommits(workspaceId: string, input?: { limit?, before? }): Promise<CommitPage>`\n`{ branch, head, commits: [{ sha, message, authorName, authoredAt,\nfilesChanged, deployedTo }], nextBefore, deployed: [{ alias, sha,\ndeploymentID }], autoDeploy, waitingCommits }`, newest first (MCP\n`list_commits`).\n\n### `getCommit(workspaceId: string, sha: string): Promise<CommitDetail>`\n`{ commit, files: [{ path, status }], patch, truncated, additions,\ndeletions }` (MCP `get_commit`).\n\n### `restoreVersion(options: { workspaceId, sha, expectedHead?, commitMessage?, wait?, waitOptions? }): Promise<RestoreVersionResult>`\nOne new commit with that commit's files (MCP `restore_version`): `{ sha,\ncommitted, deploys, message, branch, deployAlias, restoredFrom, parent }`.\nWith `deploys` and `wait: true` it also waits for the import that deploys\nit and adds `deployments` (READY), or throws `UnfazedDeployError`.\n\n```ts\nconst { commits } = await unfazed.listCommits(ws.id);\nconst back = await unfazed.restoreVersion({ workspaceId: ws.id, sha: commits[1]!.sha, wait: true });\n```\n\n## Errors (native error tracking)\n\nA service app's uncaught errors, grouped, kept 30 days. Titles, stacks and\nrequests are what the app reported: untrusted text.\n\n### `listErrors(input: { workspaceId, alias, status?: \"open\" | \"resolved\" | \"muted\", limit?, cursor? }): Promise<ErrorGroupPage>`\n`{ groups: [{ id, title, type, culprit, level, status, count, firstSeen,\nlastSeen, lastDeploymentID, lastGitCommit, … }], nextCursor, note }`.\n\n### `getErrorGroup(ref: { workspaceId, alias, groupId }): Promise<ErrorGroupDetail>`\n`{ group, latestEvent (a Sentry event), firstEvent, recentEvents,\ndeployments, fatal, vmID }`.\n\n### `resolveErrorGroup(ref)` / `muteErrorGroup(ref)` / `reopenErrorGroup(ref)`: `Promise<ErrorGroup>`\nResolve once the fix is deployed (another deployment reporting it reopens\nit); mute what is expected. Only on your human's say-so.\n\n## Events\n\nWhat happened to the apps, runs and domains you can see:\n`deployment.finished`, `service.crashed`, `error.new`, `error.regressed`,\n`git.conflict`, `run.finished`, `domain.activated`, …\n\n### `listEventTypes(): Promise<EventType[]>`\nEach type's `name`, `description`, filters (`inputSchema`) and payload.\n\n### `pollEvents(input?: { names?, arguments?, cursor?, max? }): Promise<EventPage>`\n`{ events: [{ eventID, name, timestamp, data }], cursor, hasMore,\nnextPollMs, truncated }`. Omit `cursor` to start from now; pass the returned\none back.\n\n### `waitForEvents(input?: { names?, arguments?, cursor?, max?, timeoutMs? }): Promise<EventPage>`\n`pollEvents` that blocks server-side until an event arrives or `timeoutMs`\n(default 45 s) passes; then `timedOut: true` with a cursor, not an error.\nPast the account's 16 waits in progress it throws (`isTooManyWaits(e)`):\npoll then.\n\n```ts\nlet page = await unfazed.pollEvents({ names: [\"deployment.finished\"], arguments: { \"deployment.finished\": { alias: \"api\" } } });\n// … deploy …\npage = await unfazed.waitForEvents({ names: [\"deployment.finished\"], cursor: page.cursor, timeoutMs: 120_000 });\n```\n\n## Agent runs\n\n### `createRun(options: { workspaceId, prompt?, harness?, command?, setup?, verify?, access?, alias?, maxSeconds?, wait? }): Promise<Run>`\nA one-shot agent run in a fresh VM. `wait: true` polls to SUCCEEDED,\nFAILED or CANCELLED (all returned, never thrown).\n\n### `waitForRun(runId: string, waitOptions?: WaitOptions): Promise<Run>`\n\n### `getRun(runId)` / `listRuns(filter?: { workspaceId?, status?, limit?, offset? })` / `cancelRun(runId)`\n\n### `followUpRun(runId: string, options: { prompt, mode?, wait? }): Promise<Run>`\n\n### `answerRun(runId: string, answer: string): Promise<Run>`\nAnswers a BLOCKED run's question.\n\n### `runEvents(runId)` / `runConsole(runId, { tailBytes? })` / `runTranscript(runId, { tailBytes? })`\n\n### `listRunHarnesses(): Promise<RunHarness[]>`\n\n## Anything else\n\n`unfazed.client` is the typed GraphQL transport over the same credential:\n`await unfazed.client.query(document, variables)`. `operations` exports\nevery document the SDK uses.\n";
+//# sourceMappingURL=reference.generated.js.map

package/dist/reference.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.generated.js","sourceRoot":"","sources":["../src/reference.generated.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,yDAAyD;AAEzD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,SAAS,GAAW,k6bAAk6b,CAAC","sourcesContent":["// GENERATED by scripts/embed-reference.ts from REFERENCE.md. Do not edit:\n// change REFERENCE.md and run `bun run embed-reference`.\n\n/** The SDK's reference: every method with its signature (REFERENCE.md). */\nexport const REFERENCE: string = \"# unfazed SDK reference\\n\\nEvery method of `Unfazed`, with its signature, in one page. In a script:\\n`import { Unfazed, help } from \\\"unfazed\\\"; const unfazed = new Unfazed();`\\n(run_script injects the credential; elsewhere `UNFZ_API_TOKEN` or\\n`npx unfazed login`). `help()` returns this page; `help(\\\"writeFiles\\\")` one\\nentry. Methods are async and throw an `UnfazedError` subclass on failure.\\nEvery method takes an optional last `options` with `signal` (and, for single\\nrequests, `timeoutMs`). The names follow the MCP tools: `listCommits` is\\n`list_commits`, `waitForEvents` is `wait_for_events`.\\n\\n```ts\\nimport { Unfazed } from \\\"unfazed\\\";\\n\\nexport default async () => {\\n  const unfazed = new Unfazed();\\n  const ws = await unfazed.ensureWorkspace(\\\"hello\\\");\\n  const wrote = await unfazed.writeFiles(ws.id, {\\n    \\\"server.ts\\\": `export default { fetch: () => new Response(\\\"hi\\\") }`,\\n    \\\"package.json\\\": JSON.stringify({ name: \\\"hello\\\" }),\\n  }, { commitMessage: \\\"First version\\\" });                // ONE request, ONE commit\\n  const app = await unfazed.deployService({ workspaceId: ws.id, alias: \\\"hello\\\", wait: true });\\n  return { url: app.url, commit: wrote.commit?.sha, timings: app.timings };\\n};\\n```\\n\\n## Saved, committed, deployed\\n\\nA file write has three states. **Saved**: the call returned; the app's\\nfiles have it and the next deploy uses it. **Committed**: on an app with\\nplatform git, `commit.committed && !commit.waiting`; it is in `listCommits`.\\n**Deployed**: a deploy of those files went READY (`deployService({ wait:\\ntrue })`). A write never deploys by itself, except when `commit.deploys` is\\ntrue (the branch head is imported like a push).\\n\\n`commit.waiting: true` means saved, with the commit queued for the git\\nserver: it lands in order, `sha` is null until then, nothing to retry.\\n`waitForCommit` (or `writeFiles(…, { waitForCommit: true })`) resolves once\\nit landed.\\n\\n## Workspaces\\n\\n### `createWorkspace(name: string): Promise<Workspace>`\\nA new workspace: files, env, deployments. Names are unique per owner,\\ncase-insensitively; prefer `ensureWorkspace` in re-runnable scripts.\\n\\n### `ensureWorkspace(name: string): Promise<Workspace>`\\nThe workspace named `name`, created only when missing. Safe to re-run.\\n\\n### `listWorkspaces(): Promise<Workspace[]>`\\n\\n### `liveApps(workspaceId: string): Promise<LiveApp[]>`\\nThe apps the workspace serves now: `{ alias, deploymentID, domains }`.\\n\\n### `deleteWorkspace(workspaceId: string, options?: { withDeployments?: true, confirmAliases: string[], ignoreNotFound?: boolean }): Promise<boolean>`\\nDeletes it; with `withDeployments`, every app it serves, which\\n`confirmAliases` must name exactly (`liveApps`). Kept 30 days for support.\\n\\n### `deleteApp(app: { workspaceId, alias }, options?: { ignoreNotFound?: boolean }): Promise<DeleteAppResult>`\\nDeletes one app (every deployment of the alias, its App State, env and\\nbindings); the workspace and its other apps stay.\\n\\n### `whoami(): Promise<Whoami>`\\nWho the token is, its scopes, usage and limits.\\n\\n## Files\\n\\n### `writeFiles(workspaceId: string, files: Record<string, string | { text } | { base64 } | { bytes }>, options?: { commitMessage?: string, waitForCommit?: boolean | WaitOptions, allowPartial?: boolean }): Promise<WriteFilesResult>`\\nWrites every file in ONE request, which is ONE commit on an app with\\nplatform git (MCP `write_workspace_files`). Result: `{ files: [{ path, ok,\\nerror, file }], written, failed, totalBytes, commit, commits, landed? }`;\\n`commit` is `{ sha, branch, message, committed, waiting, waitingCount,\\ndeploys, conflicts, writeSHA, paused }` or null without platform git. Not\\ntransactional: when a file fails it throws `UnfazedWriteError` (`.result`,\\n`.failed`) unless `allowPartial`. Up to 100 files and 32 MiB per request; a\\nbigger map is several requests, each a commit.\\n\\n```ts\\nconst out = await unfazed.writeFiles(ws.id, { \\\"a.ts\\\": a, \\\"logo.png\\\": { bytes } }, { commitMessage: \\\"Logo\\\" });\\nif (out.commit?.conflicts.length) console.log(\\\"a push changed\\\", out.commit.conflicts, \\\"mine:\\\", out.commit.writeSHA);\\n```\\n\\n### `writeFile(workspaceId: string, path: string, text: string, options?: { commitMessage?, waitForCommit? }): Promise<WorkspaceFile & { commit }>`\\nOne text file: `writeFiles` with one entry.\\n\\n### `writeBinaryFile(workspaceId: string, path: string, content: Uint8Array | ArrayBuffer | { base64: string }, options?): Promise<WorkspaceFile & { commit }>`\\n\\n### `waitForCommit(workspaceId: string, waitOptions?: WaitOptions): Promise<{ branch, head, waitedMs }>`\\nResolves once no write of the app waits for its commit; `head` then has\\nevery earlier write. Immediate (`head: null`) without platform git. Default\\ntimeout 2 minutes (`UnfazedTimeoutError`; the writes stay saved).\\n\\n### `readFile(workspaceId: string, path: string, input?: { offset?, limit? }): Promise<{ text, totalBytes, truncated, nextOffset, file } | null>`\\n\\n### `listFiles(workspaceId: string, input?: { limit?, offset?, order? }): Promise<WorkspaceFilePage>`\\n\\n### `deleteFile(workspaceId: string, path: string): Promise<boolean>`\\n`false` when there was nothing to delete.\\n\\n## Deploys\\n\\n### `deployService(options: { workspaceId, alias?, wait?, waitOptions?, timings?, runtime?, serviceMode?, healthPath?, cronSchedule?, cronPath? }): Promise<DeployResult>`\\nBuilds and deploys the workspace as an HTTP service (`server.ts` default\\nexport, or `unfazed.json`). Returns BUILDING at once; with `wait: true`,\\nresolves READY or throws `UnfazedDeployError` (`reason` FAILED with the\\nbuild error, or TIMEOUT; default 10 minutes). Every call is a new release;\\nthe same `alias` redeploys that app.\\n\\nWith `wait: true` the result has `timings`:\\n`{ client: { createMs, waitMs, totalMs, waitRequests, waitMode },\\nplatform: { totalMs, buildMs, promoteMs, phases, buildMode,\\nartifactTransport, buildMemoryMiB } }`, both in milliseconds. `platform` is\\nwhat the platform measured (created to READY); `client` is what you waited.\\nThe wait is server-side, so the two differ by about one round trip.\\n\\n```ts\\nconst app = await unfazed.deployService({ workspaceId: ws.id, alias: \\\"api\\\", wait: true });\\napp.timings?.platform?.phases;   // { vm_install: 900, vm_build: 2600, admission: 40, … }\\n```\\n\\n### `deployStatic(options: { workspaceId, alias?, wait?, spaMode? }): Promise<DeployResult>`\\n\\n### `deployBox(options: { workspaceId, alias, wait?, resources?: { memMiB?, vcpus?, diskGiB? } }): Promise<DeployResult>`\\nA persistent Linux VM over SSH (`sshCommand`). Always pass `alias`.\\n\\n### `deploy(input: CreateDeploymentInput, options?: { wait?, waitOptions?, timings? }): Promise<DeployResult>`\\nAny `createDeployment` input.\\n\\n### `waitForDeployment(deploymentId: string, waitOptions?: WaitOptions): Promise<Deployment>`\\nWaits server-side (MCP `wait_for_deployment`: one request per 45 s at most,\\nanswered when the status changes) until READY; throws `UnfazedDeployError`\\non FAILED or timeout. A new app's landing on its server is waited for too.\\n`waitOptions: { timeoutMs?, signal?, mode?: \\\"server\\\" | \\\"poll\\\" }`. The\\nplatform holds at most 16 waits of one account at once; past that a wait\\npolls instead.\\n\\n### `getDeployment(deploymentId: string): Promise<Deployment | null>`\\n\\n### `getDeploymentByAlias(alias: string): Promise<Deployment | null>`\\n\\n### `listDeployments(input?: { workspaceID?, alias?, kind?, limit?, offset? }): Promise<DeploymentPage>`\\nNewest first.\\n\\n### `listReleases(alias: string): Promise<Deployment[]>`\\nThe alias's history; `aliasHeld` marks the live one.\\n\\n### `rollback(options: { alias, to?, expectedCurrentId?, retries? }): Promise<Deployment>`\\nPoints the alias back at a prior READY release (default: the one before\\nthe live one). A bare `rollback({ alias })` toggles; pin `to` in anything\\nre-runnable.\\n\\n### `deleteDeployment(deploymentId: string, options?: { ignoreNotFound? }): Promise<boolean>`\\n\\n## Runtime, logs, events, timings\\n\\n### `getStatus(deploymentId: string): Promise<ServiceStatus>`\\n`{ running, health, inFlight, restartCount, memSizeMiB, lastError, … }`.\\n\\n### `getLogs(deploymentId: string, input?: { tailBytes? }): Promise<{ stdout, stderr, truncated, … }>`\\nFilter in the script: `logs.stderr.split(\\\"\\\\n\\\").filter((l) => l.includes(\\\"ERROR\\\"))`.\\n\\n### `getEvents(deploymentId: string, limit?: number): Promise<DeploymentEvent[]>`\\nThe latest `limit` (default 20) lifecycle events, oldest first: `{ type,\\ntypeEnum, severity, message, vmID, metadata, createdAt }`. `type` is the\\nevent's own name, as MCP reports it: `\\\"deployment.build_finished\\\"`,\\n`\\\"deployment.phases\\\"`, `\\\"service.vm_started\\\"`. `typeEnum` is the GraphQL\\nenum (`UNKNOWN` for names it lacks); match on `type`.\\n\\n### `getDeploymentTimings(deploymentId: string): Promise<PlatformTimings | null>`\\nA deploy's measured phases (ms) from its timing events: `{ totalMs,\\nbuildMs, promoteMs, phases, buildMode, artifactTransport, buildMemoryMiB }`.\\n`parseDeploymentTimings(events)` does the same for events you already read.\\n\\n### `restartService(deploymentId: string)` / `stopService(deploymentId: string)`\\n\\n## Env and secrets\\n\\nSnapshotted into a release at deploy time: redeploy the alias to apply.\\n\\n### `setEnv(workspaceId, name, value)` / `setSecret(workspaceId, name, value)`: `Promise<EnvVar>`\\nWorkspace defaults. A name is plain or secret, never both.\\n\\n### `setEnvMany(workspaceId: string, vars: Record<string, string>, options?: { secret?: boolean }): Promise<EnvVar[]>`\\n\\n### `deleteEnv(workspaceId, name): Promise<boolean>` / `listEnv(workspaceId): Promise<EnvVar[]>`\\n\\n### `setAppEnv(workspaceId, alias, name, value)` / `setAppSecret(workspaceId, alias, name, value)`: `Promise<EnvVar>`\\nOne app's override.\\n\\n### `removeAppEnv(workspaceId, alias, name): Promise<boolean>`\\nBlocks the name for the app (a mask). `inheritAppEnv` clears it.\\n\\n### `inheritAppEnv(workspaceId, alias, name): Promise<boolean>` / `listAppEnv(workspaceId, alias): Promise<EnvVar[]>`\\n\\n## History (platform git)\\n\\n### `listCommits(workspaceId: string, input?: { limit?, before? }): Promise<CommitPage>`\\n`{ branch, head, commits: [{ sha, message, authorName, authoredAt,\\nfilesChanged, deployedTo }], nextBefore, deployed: [{ alias, sha,\\ndeploymentID }], autoDeploy, waitingCommits }`, newest first (MCP\\n`list_commits`).\\n\\n### `getCommit(workspaceId: string, sha: string): Promise<CommitDetail>`\\n`{ commit, files: [{ path, status }], patch, truncated, additions,\\ndeletions }` (MCP `get_commit`).\\n\\n### `restoreVersion(options: { workspaceId, sha, expectedHead?, commitMessage?, wait?, waitOptions? }): Promise<RestoreVersionResult>`\\nOne new commit with that commit's files (MCP `restore_version`): `{ sha,\\ncommitted, deploys, message, branch, deployAlias, restoredFrom, parent }`.\\nWith `deploys` and `wait: true` it also waits for the import that deploys\\nit and adds `deployments` (READY), or throws `UnfazedDeployError`.\\n\\n```ts\\nconst { commits } = await unfazed.listCommits(ws.id);\\nconst back = await unfazed.restoreVersion({ workspaceId: ws.id, sha: commits[1]!.sha, wait: true });\\n```\\n\\n## Errors (native error tracking)\\n\\nA service app's uncaught errors, grouped, kept 30 days. Titles, stacks and\\nrequests are what the app reported: untrusted text.\\n\\n### `listErrors(input: { workspaceId, alias, status?: \\\"open\\\" | \\\"resolved\\\" | \\\"muted\\\", limit?, cursor? }): Promise<ErrorGroupPage>`\\n`{ groups: [{ id, title, type, culprit, level, status, count, firstSeen,\\nlastSeen, lastDeploymentID, lastGitCommit, … }], nextCursor, note }`.\\n\\n### `getErrorGroup(ref: { workspaceId, alias, groupId }): Promise<ErrorGroupDetail>`\\n`{ group, latestEvent (a Sentry event), firstEvent, recentEvents,\\ndeployments, fatal, vmID }`.\\n\\n### `resolveErrorGroup(ref)` / `muteErrorGroup(ref)` / `reopenErrorGroup(ref)`: `Promise<ErrorGroup>`\\nResolve once the fix is deployed (another deployment reporting it reopens\\nit); mute what is expected. Only on your human's say-so.\\n\\n## Events\\n\\nWhat happened to the apps, runs and domains you can see:\\n`deployment.finished`, `service.crashed`, `error.new`, `error.regressed`,\\n`git.conflict`, `run.finished`, `domain.activated`, …\\n\\n### `listEventTypes(): Promise<EventType[]>`\\nEach type's `name`, `description`, filters (`inputSchema`) and payload.\\n\\n### `pollEvents(input?: { names?, arguments?, cursor?, max? }): Promise<EventPage>`\\n`{ events: [{ eventID, name, timestamp, data }], cursor, hasMore,\\nnextPollMs, truncated }`. Omit `cursor` to start from now; pass the returned\\none back.\\n\\n### `waitForEvents(input?: { names?, arguments?, cursor?, max?, timeoutMs? }): Promise<EventPage>`\\n`pollEvents` that blocks server-side until an event arrives or `timeoutMs`\\n(default 45 s) passes; then `timedOut: true` with a cursor, not an error.\\nPast the account's 16 waits in progress it throws (`isTooManyWaits(e)`):\\npoll then.\\n\\n```ts\\nlet page = await unfazed.pollEvents({ names: [\\\"deployment.finished\\\"], arguments: { \\\"deployment.finished\\\": { alias: \\\"api\\\" } } });\\n// … deploy …\\npage = await unfazed.waitForEvents({ names: [\\\"deployment.finished\\\"], cursor: page.cursor, timeoutMs: 120_000 });\\n```\\n\\n## Agent runs\\n\\n### `createRun(options: { workspaceId, prompt?, harness?, command?, setup?, verify?, access?, alias?, maxSeconds?, wait? }): Promise<Run>`\\nA one-shot agent run in a fresh VM. `wait: true` polls to SUCCEEDED,\\nFAILED or CANCELLED (all returned, never thrown).\\n\\n### `waitForRun(runId: string, waitOptions?: WaitOptions): Promise<Run>`\\n\\n### `getRun(runId)` / `listRuns(filter?: { workspaceId?, status?, limit?, offset? })` / `cancelRun(runId)`\\n\\n### `followUpRun(runId: string, options: { prompt, mode?, wait? }): Promise<Run>`\\n\\n### `answerRun(runId: string, answer: string): Promise<Run>`\\nAnswers a BLOCKED run's question.\\n\\n### `runEvents(runId)` / `runConsole(runId, { tailBytes? })` / `runTranscript(runId, { tailBytes? })`\\n\\n### `listRunHarnesses(): Promise<RunHarness[]>`\\n\\n## Anything else\\n\\n`unfazed.client` is the typed GraphQL transport over the same credential:\\n`await unfazed.client.query(document, variables)`. `operations` exports\\nevery document the SDK uses.\\n\";\n"]}

package/dist/reference.js

@@ -0,0 +1,38 @@
+import { REFERENCE } from "./reference.generated.js";
+export { REFERENCE };
+/**
+ * The SDK's reference, for a script (or a model) that needs a signature:
+ * every method of {@link Unfazed} with its parameters, result and an
+ * example, in one page (REFERENCE.md). It describes THIS version, the one
+ * the script imported (`VERSION`): exactly what `help()` should answer.
+ *
+ * ```ts
+ * import { help } from "unfazed";
+ * export default () => help("writeFiles");   // run_script returns the entry
+ * ```
+ *
+ * `help()` is the whole page; `help(topic)` the entries whose heading names
+ * it (a method like `"restoreVersion"`, or a section like `"Events"`), or the
+ * list of methods when nothing matches.
+ */
+export function help(topic) {
+    if (!topic)
+        return REFERENCE;
+    const wanted = topic.trim().replace(/\(\)$/, "").toLowerCase();
+    const firstLine = (block) => block.split("\n", 1)[0].toLowerCase();
+    // A section ("Events", "Files"): the whole of it.
+    const section = REFERENCE.split(/\n(?=## )/).find((block) => firstLine(block) === `## ${wanted}`);
+    if (section)
+        return section.trim() + "\n";
+    // A method: every entry whose heading names it.
+    const method = new RegExp(`\`${escape(wanted)}\\(|[ /]${escape(wanted)}\\(`);
+    const matches = REFERENCE.split(/\n(?=#{2,3} )/).filter((block) => block.startsWith("### ") && method.test(firstLine(block)));
+    if (matches.length > 0)
+        return matches.map((block) => block.trim()).join("\n\n") + "\n";
+    const names = [...REFERENCE.matchAll(/^### `(\w+)\(/gm)].map((m) => m[1]);
+    return `No entry for "${topic}". Methods: ${names.join(", ")}. help() returns the whole reference.\n`;
+}
+function escape(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=reference.js.map

package/dist/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../src/reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,IAAI,CAAC,KAAc;IACjC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC/D,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,CAAC;IAC5E,kDAAkD;IAClD,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,MAAM,MAAM,EAAE,CAAC,CAAC;IAClG,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC;IAC1C,gDAAgD;IAChD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,WAAW,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7E,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,MAAM,CACrD,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CACrE,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACxF,MAAM,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,OAAO,iBAAiB,KAAK,eAAe,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,yCAAyC,CAAC;AACxG,CAAC;AAED,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACrD,CAAC","sourcesContent":["import { REFERENCE } from \"./reference.generated.js\";\n\nexport { REFERENCE };\n\n/**\n * The SDK's reference, for a script (or a model) that needs a signature:\n * every method of {@link Unfazed} with its parameters, result and an\n * example, in one page (REFERENCE.md). It describes THIS version, the one\n * the script imported (`VERSION`): exactly what `help()` should answer.\n *\n * ```ts\n * import { help } from \"unfazed\";\n * export default () => help(\"writeFiles\");   // run_script returns the entry\n * ```\n *\n * `help()` is the whole page; `help(topic)` the entries whose heading names\n * it (a method like `\"restoreVersion\"`, or a section like `\"Events\"`), or the\n * list of methods when nothing matches.\n */\nexport function help(topic?: string): string {\n  if (!topic) return REFERENCE;\n  const wanted = topic.trim().replace(/\\(\\)$/, \"\").toLowerCase();\n  const firstLine = (block: string) => block.split(\"\\n\", 1)[0]!.toLowerCase();\n  // A section (\"Events\", \"Files\"): the whole of it.\n  const section = REFERENCE.split(/\\n(?=## )/).find((block) => firstLine(block) === `## ${wanted}`);\n  if (section) return section.trim() + \"\\n\";\n  // A method: every entry whose heading names it.\n  const method = new RegExp(`\\`${escape(wanted)}\\\\(|[ /]${escape(wanted)}\\\\(`);\n  const matches = REFERENCE.split(/\\n(?=#{2,3} )/).filter(\n    (block) => block.startsWith(\"### \") && method.test(firstLine(block)),\n  );\n  if (matches.length > 0) return matches.map((block) => block.trim()).join(\"\\n\\n\") + \"\\n\";\n  const names = [...REFERENCE.matchAll(/^### `(\\w+)\\(/gm)].map((m) => m[1]);\n  return `No entry for \"${topic}\". Methods: ${names.join(\", \")}. help() returns the whole reference.\\n`;\n}\n\nfunction escape(text: string): string {\n  return text.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n"]}

package/dist/remote/app.js

@@ -20,7 +20,8 @@ export function resolveAlias(options) {
     const text = readText(path);
     const hint = `Set ${APP_ENV_VAR} to the app's alias (the <alias> of https://<alias>.unfz.to), e.g.\n` +
         `  ${APP_ENV_VAR}=my-app npx workflow inspect runs --backend unfazed\n` +
-        `or run it from the app's directory with "alias" in its ${MANIFEST_FILE}.`;
+        `or run it from the app's directory with "alias" in its ${MANIFEST_FILE}. ` +
+        `(\`npx unfazed workflow …\` takes --app my-app.)`;
     if (text === undefined)
         throw new UnfazedConfigError(`unfazed: which app? ${APP_ENV_VAR} is not set and there is no ${path}. ${hint}`);
     let manifest;

package/dist/remote/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/remote/app.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which app the `unfazed` CLI backend reads: `UNFZ_APP`, else the alias the\n * current directory's `unfazed.json` names.\n */\nimport { UnfazedConfigError } from \"../errors.js\";\n\n/** Environment variable naming the app (its alias) the CLI backend reads. */\nexport const APP_ENV_VAR = \"UNFZ_APP\";\n\n/** The project file the alias is read from when `UNFZ_APP` is unset. */\nexport const MANIFEST_FILE = \"unfazed.json\";\n\ntype Env = Record<string, string | undefined>;\n\ninterface Manifest {\n  alias?: unknown;\n  apps?: { alias?: unknown; rootDir?: unknown }[];\n}\n\n/**\n * The app alias: `alias` when given, else `UNFZ_APP`, else `unfazed.json` in\n * `cwd`: its `alias`, or the alias of its only `apps[]` entry. Throws\n * {@link UnfazedConfigError} saying what to set when none of them names one.\n */\nexport function resolveAlias(options: { alias?: string; env: Env; cwd: string }): string {\n  const explicit = options.alias?.trim() || options.env[APP_ENV_VAR]?.trim();\n  if (explicit) return explicit;\n\n  const path = joinPath(options.cwd, MANIFEST_FILE);\n  const text = readText(path);\n  const hint =\n    `Set ${APP_ENV_VAR} to the app's alias (the <alias> of https://<alias>.unfz.to), e.g.\\n` +\n    `  ${APP_ENV_VAR}=my-app npx workflow inspect runs --backend unfazed\\n` +\n    `or run it from the app's directory with \"alias\" in its ${MANIFEST_FILE}.`;\n  if (text === undefined) throw new UnfazedConfigError(`unfazed: which app? ${APP_ENV_VAR} is not set and there is no ${path}. ${hint}`);\n\n  let manifest: Manifest;\n  try {\n    manifest = JSON.parse(text) as Manifest;\n  } catch (error) {\n    throw new UnfazedConfigError(`unfazed: ${path} is not valid JSON (${(error as Error).message}). ${hint}`);\n  }\n  if (typeof manifest.alias === \"string\" && manifest.alias.trim()) return manifest.alias.trim();\n  const aliases = (Array.isArray(manifest.apps) ? manifest.apps : [])\n    .map((app) => (typeof app?.alias === \"string\" ? app.alias.trim() : \"\"))\n    .filter((alias) => alias !== \"\");\n  if (aliases.length === 1) return aliases[0]!;\n  if (aliases.length > 1) {\n    throw new UnfazedConfigError(\n      `unfazed: ${path} deploys ${aliases.length} apps (${aliases.join(\", \")}). ` +\n        `Set ${APP_ENV_VAR} to the one to inspect, e.g. ${APP_ENV_VAR}=${aliases[0]}.`,\n    );\n  }\n  throw new UnfazedConfigError(`unfazed: which app? ${path} names no \"alias\" and no apps[]. ${hint}`);\n}\n\n/** The current directory, or `\".\"` where there is no `process`. */\nexport function currentDirectory(): string {\n  const proc = (globalThis as { process?: { cwd?: () => string } }).process;\n  return proc?.cwd?.() ?? \".\";\n}\n\n/**\n * A file's text, or `undefined` when it does not exist. `node:fs` comes from\n * `process.getBuiltinModule` (Node >= 20.16, Bun, Deno), never from an\n * import: the root entry stays free of Node imports, so a browser bundle of\n * `unfazed` does not trip over them.\n */\nfunction readText(path: string): string | undefined {\n  const proc = (globalThis as { process?: { getBuiltinModule?: (id: string) => unknown } }).process;\n  const fs = proc?.getBuiltinModule?.(\"node:fs\") as\n    | { readFileSync(path: string, encoding: \"utf8\"): string }\n    | undefined;\n  if (!fs) {\n    throw new UnfazedConfigError(\n      `unfazed: cannot read ${path} on this runtime (it needs process.getBuiltinModule: Node >= 20.16, Bun or Deno). ` +\n        `Set ${APP_ENV_VAR} to the app's alias.`,\n    );\n  }\n  try {\n    return fs.readFileSync(path, \"utf8\");\n  } catch (error) {\n    if ((error as { code?: string }).code === \"ENOENT\") return undefined;\n    throw new UnfazedConfigError(`unfazed: could not read ${path}: ${(error as Error).message}`);\n  }\n}\n\nfunction joinPath(dir: string, file: string): string {\n  return dir.endsWith(\"/\") || dir.endsWith(\"\\\\\") ? dir + file : `${dir}/${file}`;\n}\n"]}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/remote/app.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which app the `unfazed` CLI backend reads: `UNFZ_APP`, else the alias the\n * current directory's `unfazed.json` names.\n */\nimport { UnfazedConfigError } from \"../errors.js\";\n\n/** Environment variable naming the app (its alias) the CLI backend reads. */\nexport const APP_ENV_VAR = \"UNFZ_APP\";\n\n/** The project file the alias is read from when `UNFZ_APP` is unset. */\nexport const MANIFEST_FILE = \"unfazed.json\";\n\ntype Env = Record<string, string | undefined>;\n\ninterface Manifest {\n  alias?: unknown;\n  apps?: { alias?: unknown; rootDir?: unknown }[];\n}\n\n/**\n * The app alias: `alias` when given, else `UNFZ_APP`, else `unfazed.json` in\n * `cwd`: its `alias`, or the alias of its only `apps[]` entry. Throws\n * {@link UnfazedConfigError} saying what to set when none of them names one.\n */\nexport function resolveAlias(options: { alias?: string; env: Env; cwd: string }): string {\n  const explicit = options.alias?.trim() || options.env[APP_ENV_VAR]?.trim();\n  if (explicit) return explicit;\n\n  const path = joinPath(options.cwd, MANIFEST_FILE);\n  const text = readText(path);\n  const hint =\n    `Set ${APP_ENV_VAR} to the app's alias (the <alias> of https://<alias>.unfz.to), e.g.\\n` +\n    `  ${APP_ENV_VAR}=my-app npx workflow inspect runs --backend unfazed\\n` +\n    `or run it from the app's directory with \"alias\" in its ${MANIFEST_FILE}. ` +\n    `(\\`npx unfazed workflow …\\` takes --app my-app.)`;\n  if (text === undefined) throw new UnfazedConfigError(`unfazed: which app? ${APP_ENV_VAR} is not set and there is no ${path}. ${hint}`);\n\n  let manifest: Manifest;\n  try {\n    manifest = JSON.parse(text) as Manifest;\n  } catch (error) {\n    throw new UnfazedConfigError(`unfazed: ${path} is not valid JSON (${(error as Error).message}). ${hint}`);\n  }\n  if (typeof manifest.alias === \"string\" && manifest.alias.trim()) return manifest.alias.trim();\n  const aliases = (Array.isArray(manifest.apps) ? manifest.apps : [])\n    .map((app) => (typeof app?.alias === \"string\" ? app.alias.trim() : \"\"))\n    .filter((alias) => alias !== \"\");\n  if (aliases.length === 1) return aliases[0]!;\n  if (aliases.length > 1) {\n    throw new UnfazedConfigError(\n      `unfazed: ${path} deploys ${aliases.length} apps (${aliases.join(\", \")}). ` +\n        `Set ${APP_ENV_VAR} to the one to inspect, e.g. ${APP_ENV_VAR}=${aliases[0]}.`,\n    );\n  }\n  throw new UnfazedConfigError(`unfazed: which app? ${path} names no \"alias\" and no apps[]. ${hint}`);\n}\n\n/** The current directory, or `\".\"` where there is no `process`. */\nexport function currentDirectory(): string {\n  const proc = (globalThis as { process?: { cwd?: () => string } }).process;\n  return proc?.cwd?.() ?? \".\";\n}\n\n/**\n * A file's text, or `undefined` when it does not exist. `node:fs` comes from\n * `process.getBuiltinModule` (Node >= 20.16, Bun, Deno), never from an\n * import: the root entry stays free of Node imports, so a browser bundle of\n * `unfazed` does not trip over them.\n */\nfunction readText(path: string): string | undefined {\n  const proc = (globalThis as { process?: { getBuiltinModule?: (id: string) => unknown } }).process;\n  const fs = proc?.getBuiltinModule?.(\"node:fs\") as\n    | { readFileSync(path: string, encoding: \"utf8\"): string }\n    | undefined;\n  if (!fs) {\n    throw new UnfazedConfigError(\n      `unfazed: cannot read ${path} on this runtime (it needs process.getBuiltinModule: Node >= 20.16, Bun or Deno). ` +\n        `Set ${APP_ENV_VAR} to the app's alias.`,\n    );\n  }\n  try {\n    return fs.readFileSync(path, \"utf8\");\n  } catch (error) {\n    if ((error as { code?: string }).code === \"ENOENT\") return undefined;\n    throw new UnfazedConfigError(`unfazed: could not read ${path}: ${(error as Error).message}`);\n  }\n}\n\nfunction joinPath(dir: string, file: string): string {\n  return dir.endsWith(\"/\") || dir.endsWith(\"\\\\\") ? dir + file : `${dir}/${file}`;\n}\n"]}

package/dist/remote/world.d.ts

@@ -2,11 +2,11 @@ import { type FetchLike } from "../client.js";
 export interface RemoteWorldOptions {
     /** The app's alias. Default: `UNFZ_APP`, else the `alias` (or single `apps[]` entry) of `unfazed.json` in `cwd`. */
     alias?: string;
-    /** Bearer token. Default: `UNFZ_API_TOKEN`. Get one at https://unfazed.dev/auth.md. */
+    /** Bearer token. Default: `UNFZ_API_TOKEN`, else the stored login of `npx unfazed login`. */
     token?: string;
     /** Full GraphQL endpoint. Default: `UNFZ_API_URL`, else https://unfazed.dev/query. */
     endpoint?: string;
-    /** Where the defaults above are read from. Default: `process.env`. */
+    /** Where the defaults above (and the stored login's location) are read from. Default: `process.env`. */
     env?: Record<string, string | undefined>;
     /** Directory whose `unfazed.json` names the app. Default: the current directory. */
     cwd?: string;

package/dist/remote/world.js

@@ -1,4 +1,5 @@
 import { ENDPOINT_ENV_VAR, TOKEN_ENV_VAR, UnfazedClient, VERSION } from "../client.js";
+import { LOGIN_COMMAND } from "../credentials.js";
 import { UnfazedAuthError, UnfazedGraphQLError, UnfazedHTTPError, UnfazedInspectError } from "../errors.js";
 import { APP_ENV_VAR, currentDirectory, resolveAlias } from "./app.js";
 import * as docs from "./documents.js";
@@ -28,24 +29,37 @@ const REDACTED = "[redacted]";
  */
 export function createRemoteWorld(options = {}) {
     const env = options.env ?? globalThis.process?.env ?? {};
-    const token = options.token ?? env[TOKEN_ENV_VAR];
-    if (!token?.trim()) {
+    const endpointEnv = env[ENDPOINT_ENV_VAR];
+    let client;
+    try {
+        // The token is `token`, else UNFZ_API_TOKEN, else the stored login of
+        // `npx unfazed login` (refreshed as it expires), all read from `env`.
+        client = new UnfazedClient({
+            ...(options.token ? { token: options.token } : {}),
+            env,
+            endpoint: options.endpoint ?? (endpointEnv ? normalizeEndpoint(endpointEnv) : undefined),
+            timeoutMs: options.timeoutMs ?? 60_000,
+            userAgent: `unfazed-sdk/${VERSION} (workflow-cli-backend)`,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof UnfazedAuthError))
+            throw error;
         const inApp = env["UNFZ_STATE_URL"]
             ? ' Inside an unfazed app the World is unfazed/workflow (its Nitro module, or setWorld(createWorld()) from "unfazed/workflow"); ' +
                 "WORKFLOW_TARGET_WORLD=unfazed selects this read-only CLI backend instead."
             : "";
-        throw new UnfazedAuthError(`unfazed: no API token. Set ${TOKEN_ENV_VAR} to inspect an app's workflow runs ` +
-            `(a token with the unfz:read scope; unfz:deploy too for cancel and wake). Get one at https://unfazed.dev/auth.md.${inApp}`);
+        // A login for another control plane says which command fixes it; keep that.
+        const message = error.message.includes("the stored login is for")
+            ? error.message
+            : `unfazed: not signed in. Run \`${LOGIN_COMMAND}\` to inspect your apps' workflow runs with your own account, ` +
+                `or set ${TOKEN_ENV_VAR} (a token with the unfz:read scope; unfz:deploy too for cancel and wake; ` +
+                `an agent gets one at https://unfazed.dev/auth.md).`;
+        throw new UnfazedAuthError(message + inApp, { cause: error });
     }
     const alias = resolveAlias({ alias: options.alias, env, cwd: options.cwd ?? currentDirectory() });
-    const endpointEnv = env[ENDPOINT_ENV_VAR];
-    const client = new UnfazedClient({
-        token,
-        endpoint: options.endpoint ?? (endpointEnv ? normalizeEndpoint(endpointEnv) : undefined),
-        timeoutMs: options.timeoutMs ?? 60_000,
-        userAgent: `unfazed-sdk/${VERSION} (workflow-cli-backend)`,
-        ...(options.fetch ? { fetch: options.fetch } : {}),
-    });
+    const authSource = client.authSource;
     const pollMaxMs = Math.max(1, options.streamPollMs ?? 5_000);
     const pollMinMs = Math.min(STREAM_POLL_MIN_MS, pollMaxMs);
     let closed = false;
@@ -66,7 +80,7 @@ export function createRemoteWorld(options = {}) {
             return await client.request(document, variables);
         }
         catch (error) {
-            throw translate(error, alias, runId);
+            throw translate(error, alias, runId, authSource);
         }
     }
     // ---- Run pages: one relay serves runs.get, hooks, streams.list ----
@@ -541,9 +555,11 @@ function syntheticEvent(runId, data) {
  * missing run is `WorkflowRunNotFoundError` (404), a refused token says how
  * to get one, a token without the deploy scope says what needs it.
  */
-function translate(error, alias, runId) {
-    const refused = (status, cause) => new UnfazedInspectError(`unfazed: the platform refused the API token (HTTP ${status}). Check ${TOKEN_ENV_VAR}; ` +
-        "get a token at https://unfazed.dev/auth.md.", { status, cause });
+function translate(error, alias, runId, authSource) {
+    const refused = (status, cause) => new UnfazedInspectError(authSource === "login"
+        ? `unfazed: the platform refused the stored login (HTTP ${status}). Run \`${LOGIN_COMMAND}\` again.`
+        : `unfazed: the platform refused the API token (HTTP ${status}). Check ${TOKEN_ENV_VAR}; ` +
+            `sign in with \`${LOGIN_COMMAND}\` instead, or get an agent token at https://unfazed.dev/auth.md.`, { status, cause });
     if (error instanceof UnfazedHTTPError) {
         if (error.status === 401 || error.status === 403)
             return refused(error.status, error);