feat(plugin): provide SDK v2

[eXamadeus]

What does this PR do?

Fixes #7641

Provides two SDK clients (v1 and v2) to avoid backwards-compatibility issues and allow plugin authors to utilize the latest SDK.

This keeps the original client intact, allowing plugin authors to adopt SDK v2 incrementally without forcing immediate migration. Breaking changes until the next major release.

@aryasaatvik has closed #7639 in favor of working together on this one. Thanks for the help!

Important

This is not a breaking change. That said, we likely wouldn't want a clientNext and client forever. I would be glad to help plan out a full migration down the road, assuming this gets merged.

How did you verify your code works?

• Type checks
• I maintain a plugin built using this fork

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Based on my search, I found one potentially related PR:

PR #8380: feat(plugin): use SDK v2

• feat(plugin): use SDK v2 #8380
• Same title as the current PR, likely an earlier iteration or related implementation of SDK v2 for plugins

This PR appears to be related as it addresses the same feature (SDK v2 plugin support). You may want to review its status and any discussion to understand how it relates to the current PR #12042.

[eXamadeus]

The bot is right, it's the same PR. I changed base repos so I can maintain my fork easier.

[barisgit]

Until this is merged, I have found a very hacky solution:

import { OpencodeClient as V2OpencodeClient } from "@opencode-ai/sdk/v2";

type V2CtorInput = NonNullable<ConstructorParameters<typeof V2OpencodeClient>[0]>;
type V2RawClient = V2CtorInput["client"];

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null;
}

function getSharedRawClient(value: unknown): V2RawClient | undefined {
  if (!isRecord(value)) {
    return undefined;
  }

  const rawClient = value["_client"];
  if (!isRecord(rawClient)) {
    return undefined;
  }

  return rawClient as V2RawClient;
}

/**
 * Attempts to extract a v2 OpencodeClient from plugin context client.
 *
 * The plugin system currently exposes v1 client structure which contains
 * an internal `_client` property. This helper bridges to v2 by wrapping
 * that raw client in a v2 OpencodeClient instance.
 *
 * @param client - Plugin ctx.client (v1 structure, unknown shape)
 * @returns v2 OpencodeClient instance, or undefined if extraction fails
 *
 * @deprecated Remove once plugin context exposes native v2 client directly.
 */
export function unstable_getV2Client(
  client: unknown,
): V2OpencodeClient | undefined {
  const rawClient = getSharedRawClient(client);
  if (!rawClient) {
    return undefined;
  }

  try {
    return new V2OpencodeClient({ client: rawClient });
  } catch {
    return undefined;
  }
}

This then enables stuff like auto-rejecting tools with a message if I am away:

await v2Client.permission.reply({
  requestID: permissionID,
  reply: "reject",
  message,
});

[BugNotFoundX]

Is there any progress

[eXamadeus]

Is there any progress

I was told the goal of the maintainers is to focus on V2 for OpenCode which will fix the SDK issues. It's likely this won't ever merge and version 2.0.0 of OpenCode will solve the SDK woes.