Repository navigation
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The JS SDK hasn't changed since March while the v1 API kept moving.
workspace.diff().commitsAheadwas alwaysundefined, 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 workspaceurland 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
commitsAheadholds a number. The SDK maps the fields the API sends today and addsmodels(),inviteTeamMember(), andmodelon 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
51 passed.models()entry per online server, withserver_idand camelCasemodel_capabilitiesentries.urlshould look likehttps://getpolyscope.com/servers/<server_id>/session?workspace=<id>.commitsAheadshould be a number (on0.1.0it printsundefined). Roles should includetool_use/tool_result/thinkingfor any workspace that has run tools.inviteTeamMember("<an address you control>")returns{ email, invited: true }and sends a real email. Calling it again throws aValidationErrorwitherrorCode === "duplicate_invite".createWorkspace({ repositoryId, linearIssueUrl })sendslinear_issue_urlcorrectly, but it fails with 422linear_issue_url is requireduntil beyondcode/polyscope-website#101 is deployed. See the Technical notes.Automated coverage
commitsAheadand camelCase diff stats: covered —test/workspace.test.ts(diff)urland 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)test/workspace.test.tsmaps all five roles at runtime. The type itself is not checked in CI:tsconfig.jsonincludes onlysrc/, sonpm run typecheckskipstest/base_branch/base_commit: partly covered —test/workspace.test.tsat runtime; the type change is not checked in CI (same reason)github_reaction_*defaults: covered —test/repository.test.ts(3 tests)model,baseBranch,linearIssueUrl: covered —test/client.test.ts(2 tests),test/repository.test.ts(2 tests, incl. the prompt-string shorthand)modelon commit and pull request: covered —test/workspace.test.ts(3 tests)models(): covered —test/client.test.ts(2 tests: full shape,server_idfilter)inviteTeamMember(): covered —test/client.test.ts(success,duplicate_invite)previewUrlfilter andfindWorkspacesByPreviewUrl(): unchanged, existing tests still pass —test/client.test.ts(2 tests)Measured:
npm run typecheckclean,npm test51 passed in 6 files (31 before).npm run buildsucceeds. Each type-level break below was also confirmed with a throwaway probe file (one@ts-expect-errorper break) compiled withtscagainstsrc/andtest/. The probe is not part of this PR.Technical notes
Where the shapes come from. Relayed responses come from
beyondcode/polyscope@379eff49, website responses frombeyondcode/polyscope-website@22ac35d.Diff:
packages/server/src/services/diff.ts:313-320returnscommitsAhead, and its non-git early return at:191does too. Stats keys arefilesChanged/additions/deletions(packages/shared/src/protocol.ts:942-946). The website passes the object through unchanged (WorkspaceActionController.php:96). The SDK fix is atsrc/resources/workspace.ts:101.Workspace fields:
packages/shared/src/protocol.ts:36-75andpackages/server/src/db/worktrees.ts:8-30.base_branch/base_commitare nullable columns (packages/server/src/db/schema.ts:44-45). Status isactive|merged|archived(schema.ts:32-35).Which endpoint sends what:
preview_urlcomes only from the list endpoint (services/worktree.ts:775-780,:1004-1016).repository/agent/statscome only from GET by id (ws-handlers/api.ts:463-472).api.ts:530).server_idandurlon list, create and show (WorkspaceController.php:92-103).The class now turns every field an endpoint leaves out into
null(orfalse/"chat") instead ofundefined.Message roles:
user|assistant|tool_use|tool_result|thinking(schema.ts:81-83,protocol.ts:251). Nothing in the server's db layer orapi.tswritessystem.Repository:
protocol.ts:3-34,schema.ts:5-21.github_reaction_*were replaced bygithub_assign_self_enabledinpolyscope@711446a07(2026-02-26). They're kept as@deprecatedand default tofalse/null, so existing reads keep their types. They're dropped fromtoJSON()because the API doesn't send them. ThattoJSON()output was already missing them in practice:undefinedvalues vanish inJSON.stringify.Create params: validation is at
WorkspaceController.php:110-119.promptandbase_branchare only forwarded on a plain create (:150-157), never together withissue_url/pull_request_url/linear_issue_url. A one-line JSDoc on both params says so. The body builder is shared byPolyscope.createWorkspace()andRepository.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:147vsapi.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.0inpackage.json,package-lock.jsonand theUser-Agent(src/http.ts:6), because of the type-level breaks below. Publishing to npm stays manual; the publish workflow was removed ined4a3b3.Commit/PR
model:WorkspaceActionController.php:35-42,:50-63. The new signature iscommit({ model }), an options object likepullRequest().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-38builds the outer object with snake_case keys and passes the server'smodelCapabilitiesentries through unchanged. That's whyServerModelshasserverId/agents/models/modelCapabilitieswhile the capability entries keep camelCase keys (displayName,supportsFastMode, …,protocol.ts:328-337). This mirrorsServerModels/AvailableAgentin 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 typedTeamInvite { email, invited }. Laravel's PR diff().commitsAhead works, plus models(), team invites and the current workspace fields #1 returns aGenericResource, but in TS that would make both fieldsunknown. A 422duplicate_invite/self_invitearrives asValidationErrorwitherrorCodeset. A token whose user owns no team gets a 403ForbiddenError(StoreTeamInviteRequest::authorize).Type-level breaking changes, hence
0.2.0. Runtime behaviour only gets more correct. Code that compiled against0.1.0can stop compiling:Message.role/MessageData.roleloses"system"and gains"tool_use" | "tool_result" | "thinking".role === "system"becomes a compile error, and exhaustive switches over the role need the new cases.Workspace.status,WorkspaceData.statusandListWorkspacesParams.statusnarrow fromstringto"active" | "merged" | "archived".status: "running"or"idle"becomes a compile error. It used to return[]silently.Workspace.baseBranch/baseCommitbecomestring | null.WorkspaceDiffData.commits_aheadis nowcommitsAhead. This only affects code using the raw data type.WorkspaceData.preview_url,repository,agent,statsandRepositoryData.github_reaction_*become optional. This only affects code reading the raw*Datatypes; 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 a0.1.xautomatically, breaks included, but needs an explicit bump for0.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.cloudandidentity_public_key(ServerController.php:27-28):cloudbelongs to the flag-gated cloud servers, and the identity key is E2E plumbing.seen,has_review_terminal,preview_tunnel_disabled: desktop UI state.seenisn't even in the server'sWorktreetype and only leaks through a row spread.claude_default_plan_mode/codex_default_plan_mode: the API has no plan-mode parameter to act on them.branchanduse_repo_pathon create: the server accepts them, but the website doesn't forward them.agent.statusstaysstring. The server can answeridle|working|waiting_for_input|error(api.ts:383), and narrowing it would be another type break with little gain.meta.has_moreis hardcodedfalseon the server (api.ts:701); the SDK passes it through as before.meta.cursorstaysnumber | string | null.Follow-ups
beyondcode/polyscope-js:npm run typecheckdoesn't covertest/(tsconfig.jsonincludes onlysrc), so a type mismatch in a test fixture never fails CI. A separate test tsconfig or Vitest typecheck would close that.beyondcode/polyscope-website: documentworkspace.url,models(),inviteTeamMember(),commit({ model }),pullRequest({ model })and the new create params inresources/docs/integrations/javascript-sdk.mdonce0.2.0is published.beyondcode/polyscope-chrome: it requires^0.1.0, so it needs an explicit bump to^0.2.0. Before bumping, grep forrole === "system",commits_ahead,status: "running"/"idle"and non-null uses ofbaseBranch.