AWX plugin: getAwxClient() returns undefined because getSecret("awx") doesn't exist at runtime

[weiyentan]

Root Cause

getAwxClient() in packages/awx/src/index.ts returns undefined because input.client.getSecret?.("awx") always returns undefined at runtime.

Evidence

Discovered via diagnostic tool (awx-diagnose) showing:

• ✅ options.baseUrl: "https://aap.tanscloud-internal.com" (configured correctly — server passes tuple options)
• ❌ client.getSecret: does not exist (typeof: undefined)

The getSecret method is purely a TypeScript type augmentation in packages/awx/src/opencode-augment.d.ts:

declare module '@opencode-ai/sdk' {
  interface OpencodeClient {
    getSecret?(key: string): Promise<string | undefined>;
  }
}

This augmentation:

• Is NOT in the OpenCode SDK types or runtime
• Is NOT in the OpenCode server binary
• Does NOT ship in the published npm package (files: ["dist/**", ...] excludes src/)
• Has ZERO matches searching the entire @opencode-ai SDK packages

When the ?. optional chain calls a non-existent method, it silently returns undefined,
causing getAwxClient() to fail at guard 2 (if (!token) return undefined).

AuthHook.loader — The Correct API

The OpenCode plugin SDK defines AuthHook.loader as the mechanism for retrieving stored provider credentials:

type AuthHook = {
  provider: string;
  loader?: (auth: () => Promise<Auth>, provider: Provider) => Promise<Record<string, any>>;
  methods: [...];
};

Where Auth for type: "api" is:

{ type: "api"; key: string; metadata?: Record<string, string> }

So await auth() returns { type: "api", key: "<PAT>" } — the stored bearer token.

Open Questions (Need Verification)

1. Does the OpenCode binary (v1.17.4) actually invoke loader at plugin load time?
2. What does the Record<string, any> return value get merged into?
3. Does loader work without a prior authorize() having completed?

Files Involved

• packages/awx/src/index.ts — getAwxClient() and server() entry point
• packages/awx/src/auth.ts — createAwxAuthHook() needs loader added
• packages/awx/src/opencode-augment.d.ts — fictional getSecret declaration (may be removed)
• packages/awx/src/diagnose.ts — diagnostic tool (already created)

Suggested Fix Approach

1. Modify createAwxAuthHook() to accept a token callback
2. Add loader that captures await auth().key into a module-level variable
3. Replace input.client.getSecret?.("awx") with that variable in getAwxClient()
4. Verify: restart OpenCode, run AWX tools

[weiyentan]

Grilling Session — Design Decisions

A grilling session resolved the following open questions and design decisions:

Scope

• Hybrid approach: Use AuthHook.loader as the primary token retrieval mechanism, with process.env.AWX_TOKEN as an env var fallback. This ensures the plugin works even if loader isn't called by the binary.

Token Precedence (highest to lowest)

1. AuthHook.loader / authorize() — stored credential from OpenCode provider auth
2. process.env.AWX_TOKEN — env var fallback for development/testing
3. Hard failure — return "AWX client not available"

AuthHook.loader Design

• createAwxAuthHook() accepts a callback parameter onToken: (token: string) => void
• Both loader and authorize() call onToken(token) when a token becomes available
• server() passes a callback that saves the token to a closure variable cachedToken
• The loader returns {} (empty Record) — the token is captured via callback instead

Init-Time Validation

• Deferred — moved from plugin init to first client creation (getAwxClient() cache miss)
• Removes the timing dependency (loader fires after server() returns)

Files to Change

File	Change
packages/awx/src/auth.ts	Add loader + token callback to createAwxAuthHook()
packages/awx/src/index.ts	Replace getSecret calls with cachedToken + env var fallback; defer validation
packages/awx/src/index.ts	Add process.env.AWX_TOKEN fallback in getAwxClient()
packages/awx/src/index.ts	Add process.env.AAP_BASE_URL ?? process.env.AWX_BASE_URL fallback for baseUrl
packages/awx/src/opencode-augment.d.ts	Delete — fictional method, misleading
packages/awx/tests/index.test.ts	Update mocks for new auth flow

Testing

• Update existing unit test mocks (replace getSecret mock with direct token variable)
• Add test for AWX_TOKEN env var fallback
• No integration tests for loader — needs manual verification via OpenCode restart

Prioritization

1. First: implement loader + callback in auth.ts
2. Second: update index.ts to use cachedToken + env var fallbacks
3. Third: remove opencode-augment.d.ts
4. Fourth: update tests
5. Fifth: rebuild and manually verify with OpenCode restart

[wyautomation]

Implemented in PR: #48

Summary

Fixed getAwxClient() by replacing non-existent getSecret() call with a bearer token captured via the AuthHook.loader mechanism at plugin load time.

Changes

• Added loader to createAwxAuthHook() that captures await auth().key
• Replaced input.client.getSecret?.("awx") with getAwxToken() in getAwxClient()
• Removed fictional getSecret type declaration from opencode-augment.d.ts
• All 247 tests pass

Branch

Consolidated branch: ai/develop-loop/issue-47-1782090528

[weiyentan]

Implementation Update

The AFK Develop-Loop implemented the fix per the grilling session design, with follow-up changes per code review.

What was implemented (commit 19a50ae on �i/develop-loop/issue-47-1782090528)

1. packages/awx/src/auth.ts: Added AuthHook.loader callback to createAwxAuthHook(). The loader receives �uth() from the OpenCode runtime and captures the stored PAT into a module-level variable via _awxToken. Exported getAwxToken() for tools to read the token.

2. packages/awx/src/index.ts: Replaced all input.client.getSecret?.("awx") calls with getAwxToken(). Removed init-time validation entirely — validation now happens lazily on first tool call, avoiding the lifecycle timing bug where server() reads the token before AuthHook.loader has fired.

3. packages/awx/src/opencode-augment.d.ts: Stripped the fictional getSecret module augmentation. File retained as a documentation placeholder.

4. packages/awx/tests/: All test files migrated from mocking getSecret to using __setAwxToken(). Added a dedicated AuthHook.loader test that exercises �uthHook.loader(mockAuth) and asserts getAwxToken() returns the expected token.

5. Deleted: ests/plugin-init-timeout.test.ts — obsolete after removing init-time validation.

Test Results

• 244 tests passing, 0 failed, 12 skipped (pre-existing integration/AAP-dependent tests)

Open Questions

• Whether the OpenCode binary (v1.17.4) actually invokes AuthHook.loader for the �wx provider remains unproven from unit tests alone. Needs runtime smoke testing via �wx-diagnose tool.

[weiyentan]

Cleanup Patch (commit \63b3a76)

Per review feedback, three cleanup items before merge:

1. *Removed .metrics/metrics.json* — runtime file-backed counters; .metrics/\ now gitignored at both repo root and package level.

2. *Removed \packages/awx/src/diagnose.ts* — diagnostic tool excluded from this PR (out of scope for issue AWX plugin: getAwxClient() returns undefined because getSecret("awx") doesn't exist at runtime #47's token capture fix).

3. Updated 8 stale comments across 6 files — references to \getSecret\ and init-time validation replaced with \getAwxToken()\ / \AuthHook.loader\ / lazy validation flow.

Final state

• 2 commits: \19a50ae\ (implementation) + \63b3a76\ (cleanup)
• Branch: \�i/develop-loop/issue-47-1782090528\
• Tests: 244 passing, 0 failed
• Open: Runtime verification that OpenCode binary invokes \AuthHook.loader\ — needs manual smoke testing

[weiyentan]

Final Cleanup (commit dd134d7)

• Updated 9 stale comments across auth.ts (4), tests/index.test.ts (4), tests/job-status.test.ts (1) — all references to "init-time validation" corrected to lazy/on-demand validation flow.

PR #48 now has 5 commits with dd134d7 as head. Ready for merge. Closing #47.

Verification

• ✅ server() no longer performs init-time token validation
• ✅ getAwxClient() resolves lazily from getAwxToken()
• ✅ .metrics/ gitignored, diagnose.ts removed
• ✅ All comments updated to reflect current flow
• ✅ PR head confirmed: dd134d7

Closes #47.

[weiyentan]

🔍 New Findings (2026-06-22) — Deeper Root Cause Found

After the original auth fix (PR #48), tools still weren't working because the plugin architecture itself doesn't match OpenCode's API. Here's what we discovered:

1. Export Format is Wrong

Current (broken): export default { id: "awx", server }
Should be: export const AwxPlugin: Plugin = async (ctx) => { ... }

The binary expects a named async function export, not a { id, server } object. Only 1 out of 8 real-world plugins (oh-my-opencode) uses the object pattern.

2. Options Parameter Never Passed

options?.baseUrl is always undefined because the binary doesn't pass the config tuple to the plugin. We confirmed this by analyzing 8 ecosystem plugins — zero of them receive or use an options parameter. Configuration is done via:

• process.env.* (most common)
• Config files
• client.config.get()

3. Config Tuple Format Not Supported

opencode.json uses string-only plugin registration:

{ "plugin": ["@weiyentan/opencode-plugin-awx"] }

No ["pkg", { baseUrl }] tuples.

4. Console.log Is Swallowed

Must use client.app.log() instead of console.log.

What Needs to Change

• Export: Switch from export default { id, server } to export const AwxPlugin: Plugin = async (ctx)
• baseUrl: Read from process.env.AWX_BASE_URL instead of options?.baseUrl
• Config: String-only in opencode.json
• Logging: Use client.app.log()
• npm cache: Clear ~/.cache/opencode/packages/@weiyentan/
• Auth hook: Already working — keep as-is (PAT in auth store)

See full analysis in handoff: #47 (TODO: link to any follow-up issue or PR)

[weiyentan]

PR #48 fixed the original \getSecret\ problem (auth hook + env var fallback). The remaining architectural issues (export format, config, logging) are tracked in #50.

[weiyentan]

Superseded by #50 for the remaining architectural work. The auth/token fix from PR #48 is complete.