Skip to content

diff().commitsAhead works, plus models(), team invites and the current workspace fields - #1

Open
mechelon wants to merge 1 commit into
mainfrom
v1-api-catchup
Open

mechelon wants to merge 1 commit into
mainfrom
v1-api-catchup

Conversation

@mechelon

Copy link
Copy Markdown
Member

The JS SDK hasn't changed since March while the v1 API kept moving. workspace.diff().commitsAhead was always undefined, because the SDK read a snake_case key the server never sends. The constructors also threw away every field they didn't know about, so the new workspace url and the newer workspace and repository fields never reached callers. On top of that, models(), team invites and the newer create options (model, baseBranch, linearIssueUrl) were documented on the website but missing from the SDK.

Now commitsAhead holds a number. The SDK maps the fields the API sends today and adds models(), inviteTeamMember(), and model on create, commit and pull request. The types are corrected to match what the server sends: message roles, workspace status, and nullable base branch/commit.

How to verify

  1. Run the checks:
    npm ci && npm run typecheck && npm test
    Expect a clean typecheck and 51 passed.
  2. Build, then run against a real account. The token comes from the local Polyscope settings. Pick a workspace whose branch has commits ahead of its base:
    npm run build
    node --input-type=module -e '
    import { Polyscope } from "./dist/index.js";
    const p = new Polyscope();
    console.log(JSON.stringify(await p.models(), null, 2));
    const ws = await p.workspace("<workspace-id>");
    console.log(ws.url, ws.interfaceMode, ws.model, ws.baseBranch);
    console.log((await ws.diff()).commitsAhead);
    console.log((await ws.messages()).messages.map((m) => m.role));
    '
    Expect one models() entry per online server, with server_id and camelCase model_capabilities entries. url should look like https://getpolyscope.com/servers/<server_id>/session?workspace=<id>. commitsAhead should be a number (on 0.1.0 it prints undefined). Roles should include tool_use/tool_result/thinking for any workspace that has run tools.
  3. Create with the new options:
    await p.createWorkspace({ repositoryId: "<repo-id>", prompt: "Say hi", baseBranch: "<existing-branch>", model: "<a model from models()>" });
    The workspace should start from that branch and use that model.
  4. inviteTeamMember("<an address you control>") returns { email, invited: true } and sends a real email. Calling it again throws a ValidationError with errorCode === "duplicate_invite".
  5. createWorkspace({ repositoryId, linearIssueUrl }) sends linear_issue_url correctly, but it fails with 422 linear_issue_url is required until beyondcode/polyscope-website#101 is deployed. See the Technical notes.

Automated coverage

  • commitsAhead and camelCase diff stats: covered — test/workspace.test.ts (diff)
  • url and the newer workspace fields, plus defaults when a response leaves fields out: covered — test/workspace.test.ts (2 tests), test/client.test.ts (url from GET)
  • Message role union: partly covered — test/workspace.test.ts maps all five roles at runtime. The type itself is not checked in CI: tsconfig.json includes only src/, so npm run typecheck skips test/
  • Nullable base_branch/base_commit: partly covered — test/workspace.test.ts at runtime; the type change is not checked in CI (same reason)
  • Repository fields and the deprecated github_reaction_* defaults: covered — test/repository.test.ts (3 tests)
  • Create with model, baseBranch, linearIssueUrl: covered — test/client.test.ts (2 tests), test/repository.test.ts (2 tests, incl. the prompt-string shorthand)
  • model on commit and pull request: covered — test/workspace.test.ts (3 tests)
  • models(): covered — test/client.test.ts (2 tests: full shape, server_id filter)
  • inviteTeamMember(): covered — test/client.test.ts (success, duplicate_invite)
  • previewUrl filter and findWorkspacesByPreviewUrl(): unchanged, existing tests still pass — test/client.test.ts (2 tests)
  • Round trip against the real API: not covered, manual only (steps 2–4)

Measured: npm run typecheck clean, npm test 51 passed in 6 files (31 before). npm run build succeeds. Each type-level break below was also confirmed with a throwaway probe file (one @ts-expect-error per break) compiled with tsc against src/ and test/. The probe is not part of this PR.

Technical notes

Where the shapes come from. Relayed responses come from beyondcode/polyscope@379eff49, website responses from beyondcode/polyscope-website@22ac35d.

  • Diff: packages/server/src/services/diff.ts:313-320 returns commitsAhead, and its non-git early return at :191 does too. Stats keys are filesChanged/additions/deletions (packages/shared/src/protocol.ts:942-946). The website passes the object through unchanged (WorkspaceActionController.php:96). The SDK fix is at src/resources/workspace.ts:101.

  • Workspace fields: packages/shared/src/protocol.ts:36-75 and packages/server/src/db/worktrees.ts:8-30. base_branch/base_commit are nullable columns (packages/server/src/db/schema.ts:44-45). Status is active|merged|archived (schema.ts:32-35).

  • Which endpoint sends what:

    • preview_url comes only from the list endpoint (services/worktree.ts:775-780, :1004-1016).
    • repository/agent/stats come only from GET by id (ws-handlers/api.ts:463-472).
    • Create returns the bare row (api.ts:530).
    • The website adds server_id and url on list, create and show (WorkspaceController.php:92-103).

    The class now turns every field an endpoint leaves out into null (or false/"chat") instead of undefined.

  • Message roles: user|assistant|tool_use|tool_result|thinking (schema.ts:81-83, protocol.ts:251). Nothing in the server's db layer or api.ts writes system.

  • Repository: protocol.ts:3-34, schema.ts:5-21. github_reaction_* were replaced by github_assign_self_enabled in polyscope@711446a07 (2026-02-26). They're kept as @deprecated and default to false/null, so existing reads keep their types. They're dropped from toJSON() because the API doesn't send them. That toJSON() output was already missing them in practice: undefined values vanish in JSON.stringify.

  • Create params: validation is at WorkspaceController.php:110-119. prompt and base_branch are only forwarded on a plain create (:150-157), never together with issue_url/pull_request_url/linear_issue_url. A one-line JSDoc on both params says so. The body builder is shared by Polyscope.createWorkspace() and Repository.createWorkspace() (toCreateWorkspaceBody, src/resources/workspace.ts:20).

  • Linear: the SDK sends linear_issue_url, which is the public field. The website currently forwards it to the server under the wrong key (WorkspaceController.php:147 vs api.ts:585-589), so this works end to end only once beyondcode/polyscope-website#101 is deployed. No SDK change is needed then.

  • Version: 0.2.0 in package.json, package-lock.json and the User-Agent (src/http.ts:6), because of the type-level breaks below. Publishing to npm stays manual; the publish workflow was removed in ed4a3b3.

  • Commit/PR model: WorkspaceActionController.php:35-42, :50-63. The new signature is commit({ model }), an options object like pullRequest(). commit() with no arguments now sends {} as the JSON body where it used to send no body. The website treats both the same.

  • models(): ModelController.php:33-38 builds the outer object with snake_case keys and passes the server's modelCapabilities entries through unchanged. That's why ServerModels has serverId/agents/models/modelCapabilities while the capability entries keep camelCase keys (displayName, supportsFastMode, …, protocol.ts:328-337). This mirrors ServerModels/AvailableAgent in polyscope-laravel PR diff().commitsAhead works, plus models(), team invites and the current workspace fields #1.

  • inviteTeamMember(email): TeamInviteController.php:14-48. It returns a small typed TeamInvite { email, invited }. Laravel's PR diff().commitsAhead works, plus models(), team invites and the current workspace fields #1 returns a GenericResource, but in TS that would make both fields unknown. A 422 duplicate_invite/self_invite arrives as ValidationError with errorCode set. A token whose user owns no team gets a 403 ForbiddenError (StoreTeamInviteRequest::authorize).

Type-level breaking changes, hence 0.2.0. Runtime behaviour only gets more correct. Code that compiled against 0.1.0 can stop compiling:

  1. Message.role / MessageData.role loses "system" and gains "tool_use" | "tool_result" | "thinking". role === "system" becomes a compile error, and exhaustive switches over the role need the new cases.
  2. Workspace.status, WorkspaceData.status and ListWorkspacesParams.status narrow from string to "active" | "merged" | "archived". status: "running" or "idle" becomes a compile error. It used to return [] silently.
  3. Workspace.baseBranch / baseCommit become string | null.
  4. WorkspaceDiffData.commits_ahead is now commitsAhead. This only affects code using the raw data type.
  5. WorkspaceData.preview_url, repository, agent, stats and RepositoryData.github_reaction_* become optional. This only affects code reading the raw *Data types; the class properties keep their types.

Everything else is additive. On 0.x a caret range pins the minor: polyscope-chrome (^0.1.0) picks up a 0.1.x automatically, breaks included, but needs an explicit bump for 0.2.0.

Left out on purpose:

  • /v1/sessions, /v1/cloud-servers/*: out of scope for now; both are behind a feature flag and undocumented.
  • Server.cloud and identity_public_key (ServerController.php:27-28): cloud belongs to the flag-gated cloud servers, and the identity key is E2E plumbing.
  • Workspace seen, has_review_terminal, preview_tunnel_disabled: desktop UI state. seen isn't even in the server's Worktree type and only leaks through a row spread.
  • Repository claude_default_plan_mode / codex_default_plan_mode: the API has no plan-mode parameter to act on them.
  • branch and use_repo_path on create: the server accepts them, but the website doesn't forward them.
  • agent.status stays string. The server can answer idle|working|waiting_for_input|error (api.ts:383), and narrowing it would be another type break with little gain.
  • meta.has_more is hardcoded false on the server (api.ts:701); the SDK passes it through as before. meta.cursor stays number | string | null.

Follow-ups

  • beyondcode/polyscope-js: npm run typecheck doesn't cover test/ (tsconfig.json includes only src), so a type mismatch in a test fixture never fails CI. A separate test tsconfig or Vitest typecheck would close that.
  • beyondcode/polyscope-website: document workspace.url, models(), inviteTeamMember(), commit({ model }), pullRequest({ model }) and the new create params in resources/docs/integrations/javascript-sdk.md once 0.2.0 is published.
  • beyondcode/polyscope-chrome: it requires ^0.1.0, so it needs an explicit bump to ^0.2.0. Before bumping, grep for role === "system", commits_ahead, status: "running"/"idle" and non-null uses of baseBranch.

The server sends commitsAhead, so diff().commitsAhead was always
undefined. The constructors dropped every field they didn't list, so the
workspace url and newer workspace and repository fields never reached
callers. models(), team invites and the newer create, commit and pull
request options were documented on the website but missing here.

Types now match what the server sends: message roles, workspace status
and nullable base branch and commit. Those are type-level breaks, hence
0.2.0.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant