Skip to content
Merged
4 changes: 3 additions & 1 deletion docs/docs/usage/tool.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,13 +68,15 @@ altimate-code tool daemon status
altimate-code tool daemon stop
```

`status` and `stop` locate the running daemon the same way `run` does: by project directory, CLI version, the `--connections` file (if any), whether workspace tools are on, and the caller's `ALTIMATE_CODE_CONN_*`, `ALTIMATE_DISABLE_SCHEMA_VALUES`, `ALTIMATE_INTEGRATIONS` and `ALTIMATE_DISABLE_WORKSPACE` environment variables. Run them with the same flags and variables as the call that started the daemon, or they will report no daemon running for this project even though one is.
`status` and `stop` locate the running daemon the same way `run` does: by project directory, CLI version, the `--connections` file (if any), whether workspace tools are on, and the caller's `ALTIMATE_CODE_CONN_*`, `ALTIMATE_DISABLE_SCHEMA_VALUES`, `ALTIMATE_INTEGRATIONS`, `ALTIMATE_DISABLE_WORKSPACE`, `VIRTUAL_ENV` and `CONDA_PREFIX` environment variables. The last two are part of the daemon's identity because, when `~/.altimate-code/dbt.json` sets no `pythonPath` and the project has no `.venv`, `venv` or `env` folder of its own, they pick the Python the daemon's dbt adapter runs dbt with: activating the project's virtualenv then gets a daemon that uses it rather than one started without it. A `pythonPath` in `dbt.json` always wins; change it there. Run them with the same flags and variables as the call that started the daemon, or they will report no daemon running for this project even though one is.

| Setting | Description |
|---|---|
| `ALTIMATE_TOOL_DAEMON=0` | Always run in-process. |
| `ALTIMATE_TOOL_DAEMON_IDLE_MS` | Idle time before the daemon exits (default `600000`). |

The tools that start the dbt adapter (`dbt_lineage`, `dbt_cte_profile`, `dbt_sql_graph`, `dbt_health`, `dbt_cost_estimate`, and `sql_execute` routed through dbt) have dbt write its artifacts to `<target-path>/.altimate-code/` rather than the project's own `target/` in the `core` and `corecommand` integration modes: a dbt command rewrites `manifest.json` with compiled SQL for only what it compiled, so the project's `target/manifest.json` is left as your own `dbt compile` wrote it. The `fusion` and `cloud` modes read `<project>/target` whatever dbt is told, so there dbt still writes to it.

The daemon listens on a local socket (a named pipe on Windows) under the Altimate Code state directory and removes it on exit.

## Claude Code routing
Expand Down
2 changes: 1 addition & 1 deletion packages/dbt-tools/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"scripts": {
"build": "bun build src/index.ts --outdir dist --target node --format esm && bun run script/copy-python.ts",
"typecheck": "tsc --noEmit",
"test": "bun test test/cli.test.ts test/config.test.ts test/dbt-cli.test.ts test/dbt-resolve.test.ts test/adapter-bun.test.ts test/stale-manifest.test.ts test/build-integrity.test.ts --timeout 30000",
"test": "bun test test/cli.test.ts test/config.test.ts test/dbt-cli.test.ts test/dbt-resolve.test.ts test/adapter-bun.test.ts test/stale-manifest.test.ts test/build-integrity.test.ts test/adapter-target-path.test.ts --timeout 30000",
"test:e2e": "bun test test/e2e/ --timeout 300000"
},
"dependencies": {
Expand Down
20 changes: 17 additions & 3 deletions packages/dbt-tools/src/adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,22 @@ function terminal(): DBTTerminal {
}
}

function env(cfg: Config): RuntimePythonEnvironment {
/** What `create` needs besides the saved config. */
export type CreateOptions = {
/**
* The folder dbt writes its artifacts to (manifest.json, partial_parse.msgpack, run_results.json) for
* every command this adapter runs, given to dbt as DBT_TARGET_PATH. Unset, dbt writes to the project's
* own target-path, which is what a command run for the user should do. A caller that parses and
* compiles for its own reading passes a folder of its own: dbt rewrites manifest.json on every
* command, with compiled SQL only for what that command compiled, so writing to the project's target
* would take the compiled SQL of every other model away from whoever reads that manifest.
*/
targetPath?: string
}

function env(cfg: Config, options: CreateOptions): RuntimePythonEnvironment {
const vars = { ...process.env }
if (options.targetPath) vars.DBT_TARGET_PATH = options.targetPath
return {
pythonPath: cfg.pythonPath,
getEnvironmentVariables: () => vars,
Expand All @@ -98,15 +112,15 @@ export function hasModelLineage(adapter?: DBTProjectIntegrationAdapter): boolean
return typeof target.getModelLineage === "function"
}

export async function create(cfg: Config): Promise<DBTProjectIntegrationAdapter> {
export async function create(cfg: Config, options: CreateOptions = {}): Promise<DBTProjectIntegrationAdapter> {
const config = configuration(cfg)
const term = terminal()
const factory = new DBTCommandFactory(config)

const http = new AltimateHttpClient(term, config)
const client = new DbtIntegrationClient(http, term)

const runtime = env(cfg)
const runtime = env(cfg, options)
const provider = {
getCurrentEnvironment: () => runtime,
onEnvironmentChanged: () => () => {},
Expand Down
67 changes: 67 additions & 0 deletions packages/dbt-tools/test/adapter-target-path.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
import { describe, test, expect } from "bun:test"
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs"
import { tmpdir } from "os"
import { join } from "path"
import { create } from "../src/adapter"

/** A stand-in `python` that records the DBT_TARGET_PATH each run sees and fails the bridge run. */
function recordingPython(root: string) {
const log = join(root, "target-path.log")
const python = join(root, "python")
writeFileSync(
python,
[
"#!/bin/sh",
`printf '%s\\n' "\${DBT_TARGET_PATH-unset}" >> '${log}'`,
'case "$1" in',
' --version) echo "Python 3.11.9"; exit 0 ;;',
' -c) echo "1.10.0"; exit 0 ;;',
"esac",
"exit 3",
].join("\n") + "\n",
)
chmodSync(python, 0o755)
return { python, seen: () => (existsSync(log) ? readFileSync(log, "utf8").trim().split("\n") : []) }
}

// The adapter's dbt commands rewrite manifest.json in the target folder they are given; a caller that
// compiles for its own reading gives one of its own, so the project's target/manifest.json is left alone.
describe.skipIf(process.platform === "win32")("create's target folder", () => {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This regression test is never executed by bun run test: the package script omits test/adapter-target-path.test.ts. Add the file to the package test command so target-path regressions fail CI.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/dbt-tools/test/adapter-target-path.test.ts, line 29:

<comment>This regression test is never executed by `bun run test`: the package script omits `test/adapter-target-path.test.ts`. Add the file to the package test command so target-path regressions fail CI.</comment>

<file context>
@@ -0,0 +1,66 @@
+
+// The adapter's dbt commands rewrite manifest.json in the target folder they are given; a caller that
+// compiles for its own reading gives one of its own, so the project's target/manifest.json is left alone.
+describe.skipIf(process.platform === "win32")("create's target folder", () => {
+  const start = async (targetPath?: string) => {
+    const root = mkdtempSync(join(tmpdir(), "dbt-tools-target-"))
</file context>

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 4266798: test/adapter-target-path.test.ts is now in dbt-tools' bun run test file list.

const start = async (targetPath?: string) => {
const root = mkdtempSync(join(tmpdir(), "dbt-tools-target-"))
const project = join(root, "project")
mkdirSync(project)
writeFileSync(join(project, "dbt_project.yml"), "name: p\nversion: '1.0'\nprofile: p\n")
const { python, seen } = recordingPython(root)
const saved = process.env.DBT_TARGET_PATH
delete process.env.DBT_TARGET_PATH
try {
await create(
{ projectRoot: project, pythonPath: python, dbtIntegration: "corecommand", queryLimit: 500 },
targetPath ? { targetPath } : undefined,
).then(
(adapter) => adapter.dispose(),
() => {},
)
// The host's own environment is not changed: other readers of DBT_TARGET_PATH still see the project's.
expect(process.env.DBT_TARGET_PATH).toBeUndefined()
return seen()
} finally {
if (saved === undefined) delete process.env.DBT_TARGET_PATH
else process.env.DBT_TARGET_PATH = saved
rmSync(root, { recursive: true, force: true })
}
}

test("every dbt process the adapter starts writes to the folder it is given", async () => {
const runs = await start("/tmp/project/target/.altimate-code")
expect(runs.length).toBeGreaterThan(0)
expect(new Set(runs)).toEqual(new Set(["/tmp/project/target/.altimate-code"]))
})

test("without one, dbt writes where the project says", async () => {
const runs = await start()
expect(runs.length).toBeGreaterThan(0)
expect(new Set(runs)).toEqual(new Set(["unset"]))
})
})
39 changes: 35 additions & 4 deletions packages/opencode/src/altimate/native/connections/register.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
* schema.inspect
*/

import path from "path"
import { register } from "../dispatcher"
import { listSchemaTables } from "./schema-list"
import * as Registry from "./registry"
Expand Down Expand Up @@ -57,13 +58,15 @@ let dbtAdapter: any | null | undefined = undefined
let dbtAdapterInflight: Promise<any | null> | undefined
/** The project root the cached attempt read from the dbt config; null when it found none. */
let dbtProjectRoot: string | null = null
/** The Python the cached attempt runs dbt with; null when it found no config. */
let dbtPythonPath: string | null = null

/** Test seams for the single-flight. Production leaves `readConfig` unset. */
export const dbtAdapterInternals: {
/** Replaces the dbt config read, so a test can hold an attempt open. */
readConfig?: () => Promise<unknown>
/** Replaces dbt-tools' adapter creation, so a test can see which integration modes were tried. */
create?: (config: any) => Promise<any>
create?: (config: any, options?: { targetPath?: string }) => Promise<any>
/** Replaces the check for dbt-integration's lineage, which a test's fake adapter provides itself. */
hasModelLineage?: (adapter?: unknown) => boolean
/** Adapter creation attempts since the last reset — what single-flight bounds. */
Expand Down Expand Up @@ -109,21 +112,27 @@ async function ensureDbtAdapter(): Promise<any | null> {
: await readDbtConfig()
if (dbtAdapterInflight === mine) {
dbtProjectRoot = typeof dbtConfig?.projectRoot === "string" ? dbtConfig.projectRoot : null
dbtPythonPath = typeof dbtConfig?.pythonPath === "string" ? dbtConfig.pythonPath : null
}
if (!dbtConfig) return publish(null)

// Check if dbt_project.yml exists
const fs = await import("fs")
const path = await import("path")
if (
!fs.existsSync(path.join(dbtConfig.projectRoot, "dbt_project.yml"))
) {
return publish(null)
}

// Create the adapter
// Create the adapter. Its dbt commands write their artifacts to a folder of their own: the project's
// target/manifest.json is the user's (and other tools'), and a tool's compile or show would rewrite
// it with compiled SQL for only the nodes that command compiled.
// Only in the modes whose dbt-integration reads the artifacts back from where dbt wrote them.
const create = dbtAdapterInternals.create ?? (await import("../../../../../dbt-tools/src/adapter")).create
return publish(await create(dbtConfig), dbtConfig.projectRoot)
const options = SEPARATE_TARGET_MODES.has(dbtConfig.dbtIntegration || "core")
? { targetPath: await dbtToolTargetPath(dbtConfig.projectRoot) }
: {}
return publish(await create(dbtConfig, options), dbtConfig.projectRoot)
} catch {
// dbt-tools not available or config invalid — fall back to native
return publish(null)
Expand All @@ -135,6 +144,22 @@ async function ensureDbtAdapter(): Promise<any | null> {
return mine
}

/**
* The dbt-integration modes (dbt.json's `dbtIntegration`, `core` when unset) that read the manifest back from the
* target path dbt itself reports, DBT_TARGET_PATH included. Fusion and dbt Cloud read `<project>/target` whatever
* dbt was told, so they keep writing there: a separate folder would leave them reading a manifest nothing updates.
*/
export const SEPARATE_TARGET_MODES: ReadonlySet<string> = new Set(["core", "corecommand"])

/** The folder, inside the project's target folder, where the tools' dbt adapter writes its dbt artifacts. */
export const DBT_TOOL_TARGET_DIR = ".altimate-code"

/** Where the tools' dbt adapter has dbt write manifest.json and the rest: never the project's own target folder. */
export async function dbtToolTargetPath(projectRoot: string): Promise<string> {
const { resolveDbtTargetPath } = await import("../../validators/validator-utils")
return path.join(await resolveDbtTargetPath(projectRoot), DBT_TOOL_TARGET_DIR)
}

/** Where a `warehouse`-less call would actually go. */
export type DefaultTarget =
| {
Expand Down Expand Up @@ -316,6 +341,11 @@ export async function getDbtProjectRoot(): Promise<string | undefined> {
}
}

/** The Python the dbt adapter runs dbt with, once an attempt has read the dbt config. */
export function getDbtPythonPath(): string | undefined {
return dbtPythonPath ?? undefined
}

/** Reset dbt adapter (for testing). */
export function resetDbtAdapter(): void {
dbtAdapter = undefined
Expand All @@ -326,6 +356,7 @@ export function resetDbtAdapter(): void {
dbtAdapterInternals.attempts = 0
dbtAdapterInternals.writes = 0
dbtProjectRoot = null
dbtPythonPath = null
}

// ---------------------------------------------------------------------------
Expand Down
6 changes: 4 additions & 2 deletions packages/opencode/src/altimate/tool-cli/daemon.ts
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,10 @@ export function resolveDirectory(directory: string): string {
const CONN_ENV_PREFIX = "ALTIMATE_CODE_CONN_"

// Variables a daemon reads once at spawn that change what it returns or exposes (value sampling, integration
// routing, workspace tools), so a caller with a different value must not be served by a daemon started without it.
const BEHAVIOUR_ENV = ["ALTIMATE_DISABLE_SCHEMA_VALUES", "ALTIMATE_INTEGRATIONS", "ALTIMATE_DISABLE_WORKSPACE"]
// routing, workspace tools, and the Python environment its dbt adapter runs dbt with), so a caller with a
// different value must not be served by a daemon started without it: a daemon started outside the project's
// virtualenv would otherwise go on answering that dbt didn't load after the caller activated it.
const BEHAVIOUR_ENV = ["ALTIMATE_DISABLE_SCHEMA_VALUES", "ALTIMATE_INTEGRATIONS", "ALTIMATE_DISABLE_WORKSPACE", "VIRTUAL_ENV", "CONDA_PREFIX"]

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This identity still misses PATH-based Python selection: discoverPython falls back to which/where python after the variables listed here, so changing PATH can reuse a daemon created with a different Python. Include PATH in the key, or key the resolved pythonPath, so the daemon cannot retain the wrong dbt environment.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/opencode/src/altimate/tool-cli/daemon.ts, line 50:

<comment>This identity still misses PATH-based Python selection: `discoverPython` falls back to `which`/`where python` after the variables listed here, so changing PATH can reuse a daemon created with a different Python. Include `PATH` in the key, or key the resolved `pythonPath`, so the daemon cannot retain the wrong dbt environment.</comment>

<file context>
@@ -44,8 +44,10 @@ export function resolveDirectory(directory: string): string {
+// routing, workspace tools, and the Python environment its dbt adapter runs dbt with), so a caller with a
+// different value must not be served by a daemon started without it: a daemon started outside the project's
+// virtualenv would otherwise go on answering that dbt didn't load after the caller activated it.
+const BEHAVIOUR_ENV = ["ALTIMATE_DISABLE_SCHEMA_VALUES", "ALTIMATE_INTEGRATIONS", "ALTIMATE_DISABLE_WORKSPACE", "VIRTUAL_ENV", "CONDA_PREFIX"]
 
 /** A short digest of the caller's `ALTIMATE_CODE_CONN_*` variables and the behaviour variables above, empty when
</file context>
Suggested change
const BEHAVIOUR_ENV = ["ALTIMATE_DISABLE_SCHEMA_VALUES", "ALTIMATE_INTEGRATIONS", "ALTIMATE_DISABLE_WORKSPACE", "VIRTUAL_ENV", "CONDA_PREFIX"]
const BEHAVIOUR_ENV = ["ALTIMATE_DISABLE_SCHEMA_VALUES", "ALTIMATE_INTEGRATIONS", "ALTIMATE_DISABLE_WORKSPACE", "VIRTUAL_ENV", "CONDA_PREFIX", "PATH"]

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not changing this one. PATH differs between shells, IDE terminals and the tools that call the CLI, so keying the daemon on it would start a daemon per caller and lose the warm connections the daemon exists for. Keying on the resolved pythonPath would need Python discovery (a which subprocess and the dbt config read) on every client call. The selectors discoverPython reads first, a project-local .venv/venv/env, VIRTUAL_ENV, CONDA_PREFIX and dbt.json's pythonPath, are all covered. For the PATH-only case, the refusal names the Python the daemon used and says to run altimate-code tool daemon stop.


/** A short digest of the caller's `ALTIMATE_CODE_CONN_*` variables and the behaviour variables above, empty when
* none are set. A daemon reads them once at spawn, so callers with different values must not share one. */
Expand Down
65 changes: 47 additions & 18 deletions packages/opencode/src/altimate/tool-zod-compat.ts
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,35 @@ export function zodToJsonSchema(schema: z.ZodType): JSONSchema7 {
: rest) as JSONSchema7
}

// altimate_change start — argument errors that name the field
/** The value at `path` in `input`, undefined when any step is missing. */
function valueAt(input: unknown, path: readonly PropertyKey[]): unknown {
let value = input
for (const key of path) {
if (typeof value !== "object" || value === null || !Object.hasOwn(value, key)) return undefined
value = (value as Record<PropertyKey, unknown>)[key]
}
return value
}

/**
* Each issue of a failed zod parse as one clause that names its field: `change_type is required (expected
* one of "remove"|"rename")` for a missing one, `limit: Too small: expected number to be >=1` for a wrong one.
*/
export function describeZodIssues(error: z.ZodError, input: unknown): string {
const clauses = error.issues.map((issue) => {
if (issue.path.length === 0) return issue.message
const field = issue.path.map((p, i) => (typeof p === "number" ? `[${p}]` : `${i === 0 ? "" : "."}${String(p)}`)).join("")
if (valueAt(input, issue.path) === undefined) {
const expected = issue.message.replace(/^Invalid (?:input|option):\s*/, "").replace(/,\s*received undefined$/, "")
return `${field} is required (${expected})`
}
return `${field}: ${issue.message}`
})
return clauses.length > 0 ? clauses.join("; ") : error.message
}
// altimate_change end

/** Build a `DefWithoutID` from a resolved legacy tool object (no Effect wrapper). */
function legacyDefToDef(legacy: LegacyToolDef): DefWithoutID {
const validationSchema = zodToJsonSchema(legacy.parameters)
Expand All @@ -200,24 +229,24 @@ function legacyDefToDef(legacy: LegacyToolDef): DefWithoutID {
// tool needs hidden compatibility arguments that should not be advertised.
jsonSchema: legacy.jsonSchema ?? validationSchema,
// altimate_change end
...(legacy.formatValidationError
? {
// altimate_change start — the new Tool API decodes via Schema.declare, so the
// error reaching us is an Effect SchemaIssue (no zod `.issues`/`.path`), not a
// z.ZodError. Recover the original input from Effect SchemaError.issue.actual and
// re-run the zod schema to produce the real z.ZodError the legacy formatter
// expects; fall back to the original error if recovery is impossible.
formatValidationError: (error: unknown) => {
const actual = schemaErrorActual(error)
if (actual.found) {
const parsed = legacy.parameters.safeParse(actual.value)
if (!parsed.success) return legacy.formatValidationError!(parsed.error)
}
return legacy.formatValidationError!(error as z.ZodError)
},
// altimate_change end
}
: {}),
// altimate_change start — the new Tool API decodes via Schema.declare, so the error reaching
// us is an Effect SchemaIssue (no zod `.issues`/`.path`), not a z.ZodError: on its own it reads
// "Expected <Declaration>" and names no field. Recover the original input from Effect
// SchemaError.issue.actual and re-run the zod schema to produce the real z.ZodError, for the
// legacy tool's own formatter or, when it has none, one that names each field and what it
// expects; fall back to the original error if recovery is impossible.
formatValidationError: (error: unknown) => {
const actual = schemaErrorActual(error)
if (actual.found) {
const parsed = legacy.parameters.safeParse(actual.value)
if (!parsed.success)
return legacy.formatValidationError
? legacy.formatValidationError(parsed.error)
: describeZodIssues(parsed.error, actual.value)
}
return legacy.formatValidationError ? legacy.formatValidationError(error as z.ZodError) : String(error)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[🔴 HIGH] If the error originates from Effect validation but Zod parsing unexpectedly succeeds (e.g., if the Effect schema is stricter), or if actual.found is false, this code will bypass the Zod recovery and fall through to this line.\n\nHere, error (which is likely an Effect SchemaIssue) is forcibly cast to z.ZodError and passed to legacy.formatValidationError. Since SchemaIssue lacks properties like .issues, this can cause a runtime TypeError (e.g., Cannot read properties of undefined (reading 'map')) if the legacy formatter tries to access them.\n\nAdditionally, using String(error) as a fallback may produce unhelpful generic messages if the error lacks a custom toString() method.\n\nConsider verifying if error is actually a z.ZodError before passing it to the formatter, and using error.message for Error instances to provide more resilient logging.

Suggested change:

Suggested change
return legacy.formatValidationError ? legacy.formatValidationError(error as z.ZodError) : String(error)
if (legacy.formatValidationError && error instanceof z.ZodError) {\n return legacy.formatValidationError(error)\n }\n return error instanceof Error ? error.message : String(error)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That fallthrough isn't new: origin/main already has return legacy.formatValidationError!(error as z.ZodError) for a tool with its own formatter. This PR adds the case without a formatter (describeZodIssues, or String(error) when the input can't be recovered). Hardening the existing path is out of scope here.

},
// altimate_change end
execute: (args: unknown, ctx: NewContext) =>
// altimate_change start — bridge the ambient Instance ALS into the Effect InstanceRef so
// legacy tools whose execute calls async facades (Skill.get, Agent.list, …) — which resolve
Expand Down
Loading
Loading