FactCode ADK adapter

Optional, server-side BaseLlm implementation for Google ADK. ADK owns the agent loop; the host supplies a single-call FactCode model transport. This package does not call Agent.prompt, select Gemini, read environment credentials, execute tools, or change the FactCode CLI's dependencies or defaults.

Host integration contract

Create one FactCodeLlm per invocation, with a pinned FactCode Model, trusted Context, and mandatory complete(model, context, signal) callback. The callback owns provider authorization, credentials, retry policy and usage accounting. It must respect cancellation and must not start another agent loop.

Use getInitialContents() to seed ADK's history with the matching public projection; retain the canonical FactCode history at the host. With an ADK runner, the host must seed its session history and submit the current user message exactly once. Additional instructions, model options and tool schemas must be resolved into the trusted host context/transport, not inferred from ADK request config. Output schemas, media, streaming and live connections are explicitly unsupported in this initial slice.

Supply approved ADK tools from the same host registry as Context.tools. This adapter checks tool names and call/result correlation, not authorization or schema equivalence. Tool execution must go through the platform executor; the host must enforce parameter validation, permission, timeout and audit there. A rejected tool returns { error: "STABLE_CODE" }; it is replayed as a FactCode error tool result. Other JSON objects are replayed as successful results. Multiple tool results must arrive in call order. Historical tool results are projected as { result: text } or { error: text }; their raw messages are preserved for the provider, without serializing signatures into ADK events.

Limits per invocation:

• At most six model calls; configurable downward.
• Three tool calls by default, maximum five, checked before exposing calls to ADK.
• Sixty-second total deadline, configurable downward, starting at construction.
• 256 KiB JSON ceiling for requests, responses and retained context; 64 KiB per tool result.

Errors close the invocation and expose stable codes, not provider error text. Final responses release retained history. Always call dispose() in a host finally block as well, including when a runner stops between tool rounds. Do not share instances between users or sessions. Cancellation closes the adapter even if a transport ignores its signal; the host still owns termination of any underlying external request. Token usage is returned in ADK response metadata; raw provider usage remains available to the injected transport.

Scope and rollout

PM-3069's library slice only. No tenant is enabled and no production runner, Core AI worker, authenticated IPC, runtime selector or published Docker artifact is added here. Those remain required before enabling ADK in FactVerse. Default and LEAN runtime behavior is unchanged. This package must not be added to @datamesh/factcode or factcode-agent-core dependencies.

Focused verification, from this directory:

node ../../node_modules/vitest/dist/cli.js --run test/model.test.ts

Tests use the real ADK SDK with a synthetic host transport. They require neither network access, paid model calls, GPU nor customer data. They do not establish production permission or tenant-isolation guarantees.