Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: orca-chat-visuals
description: Show a chart, diagram, table, report or mockup inline in this Orca chat as an HTML
page. Use when a visual would help the user understand your answer. Only available when the
ORCA_CHAT_VISUALS_DIR environment variable is set.
ORCA_CHAT_SCRATCH_DIR environment variable is set.
user-invocable: false
---

Expand All @@ -13,8 +13,10 @@ clearer.

## Writing the page

- Save it in the folder named by `ORCA_CHAT_VISUALS_DIR` (`printenv ORCA_CHAT_VISUALS_DIR`; in
PowerShell `$env:ORCA_CHAT_VISUALS_DIR`). If it's unset or you can't write there, skip the visual.
- Save it in the folder named by `ORCA_CHAT_SCRATCH_DIR` (`printenv ORCA_CHAT_SCRATCH_DIR`; in
PowerShell `$env:ORCA_CHAT_SCRATCH_DIR`). If it's unset or you can't write there, skip the visual.
This folder is temporary: Orca may remove it after 30 days without chat activity or changes.
Save files meant to last in the workspace.
- One complete HTML file per visual, directly in that folder, under 512 KB, with a new file name
each time (e.g. `latency-by-region-7c1e.html`): letters, digits, `.`, `_`, `-`, ending in `.html`.
- Inline your styles, scripts and data. Libraries and fonts may load only from cdn.jsdelivr.net,
Expand Down
10 changes: 7 additions & 3 deletions src/main/acp/acp-structured-launch-resolution-omp.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,10 @@ import { createAcpStructuredLaunchResolver } from '../runtime/structured-agent-l
import { describe, expect, it, vi } from 'vitest'
import type { AgentSessionRecord } from '../../shared/agent-session-record'
import { agentSessionRecordFixture } from '../../shared/agent-session-record.test-fixture'
import { NATIVE_CHAT_VISUALS_DIR_ENV } from '../native-chat/native-chat-visuals-delivery'
import {
LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV,
NATIVE_CHAT_SCRATCH_DIR_ENV
} from '../native-chat/native-chat-visuals-delivery'
import { createProviderSpawnSpec } from '../provider-process/provider-process-supervisor'
import { acpLaunchSpecFor } from './acp-launch-specs'
import { STRUCTURED_CHILD_ENV_TO_DELETE } from '../runtime/structured-session-child-env'
Expand Down Expand Up @@ -63,10 +66,11 @@ describe('OMP ACP launch resolution', () => {
ANTHROPIC_API_KEY: 'sk-test'
}
const launch = await resolver(ompRecord(), { launchEnv: userEnv })({ identity })
// Only the shared pane and hook keys, and an inherited visuals folder: this chat has none.
// Only the shared pane and hook keys, and an inherited scratch folder: this chat has none.
expect(launch.envToDelete).toEqual([
...STRUCTURED_CHILD_ENV_TO_DELETE,
NATIVE_CHAT_VISUALS_DIR_ENV
NATIVE_CHAT_SCRATCH_DIR_ENV,
LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV
])
const child = createProviderSpawnSpec(
{
Expand Down
6 changes: 4 additions & 2 deletions src/main/acp/acp-structured-launch-resolution.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,8 @@ import {
import type { StructuredAgentLaunchPartResolver } from '../runtime/structured-agent-launch-composition'
import { STRUCTURED_CHILD_ENV_TO_DELETE } from '../runtime/structured-session-child-env'
import {
NATIVE_CHAT_VISUALS_DIR_ENV,
LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV,
NATIVE_CHAT_SCRATCH_DIR_ENV,
withNativeChatVisualsEnv
} from '../native-chat/native-chat-visuals-delivery'
import type { AcpLaunchSpec } from './acp-launch-specs'
Expand Down Expand Up @@ -233,7 +234,8 @@ export function acpStructuredLaunchPart(
...STRUCTURED_CHILD_ENV_TO_DELETE,
...envToDelete,
// Without visuals, a folder Orca itself inherited (started from a chat) names another chat's.
...(skill ? [] : [NATIVE_CHAT_VISUALS_DIR_ENV])
...(skill ? [] : [NATIVE_CHAT_SCRATCH_DIR_ENV]),
LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV
]
}
}
Expand Down
32 changes: 21 additions & 11 deletions src/main/acp/acp-structured-launch-visuals.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,15 @@ import { createAcpStructuredLaunchResolver } from '../runtime/structured-agent-l
import { describe, expect, it, vi } from 'vitest'
import type { AgentSessionRecord } from '../../shared/agent-session-record'
import { agentSessionRecordFixture } from '../../shared/agent-session-record.test-fixture'
import { NATIVE_CHAT_VISUALS_DIR_ENV } from '../native-chat/native-chat-visuals-delivery'
import {
LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV,
NATIVE_CHAT_SCRATCH_DIR_ENV
} from '../native-chat/native-chat-visuals-delivery'
import { resolveProviderChildEnv } from '../provider-process/provider-process-launch'
import { acpLaunchSpecFor, type AcpLaunchSpec } from './acp-launch-specs'

const SKILL = { pluginDir: '/app/plugin', skillsRoot: '/app/plugin/skills' }
const FOLDER = '/state/native-chat-visuals/0123'
const FOLDER = '/state/chat-scratch/0123'
const identity = {
sessionId: 'session-alpha-1',
workspaceId: 'workspace-1',
Expand Down Expand Up @@ -66,23 +69,29 @@ function resolve(
}

describe('ACP launch visuals', () => {
it("gives Grok the plugin folder and the chat's visuals folder", async () => {
it("gives Grok the plugin folder and the chat's scratch folder", async () => {
const launch = await resolve('grok').launch
expect(launch.args).toEqual(['agent', '--plugin-dir', SKILL.pluginDir, 'stdio'])
expect(launch.env[NATIVE_CHAT_VISUALS_DIR_ENV]).toBe(FOLDER)
expect(launch.envToDelete).not.toContain(NATIVE_CHAT_VISUALS_DIR_ENV)
expect(launch.env[NATIVE_CHAT_SCRATCH_DIR_ENV]).toBe(FOLDER)
expect(launch.envToDelete).not.toContain(NATIVE_CHAT_SCRATCH_DIR_ENV)
// The pre-rename name is never set, and an inherited one is always stripped.
expect(launch.env).not.toHaveProperty(LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV)
expect(launch.envToDelete).toContain(LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV)
expect(
resolveProviderChildEnv(launch, { [LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV]: '/older/chat' })
).not.toHaveProperty(LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV)
})

it('starts a Grok too old for --plugin-dir without visuals, never naming an inherited folder', async () => {
const { launch, logger } = resolve('grok', {
version: '1.0.10',
inheritedEnv: { [NATIVE_CHAT_VISUALS_DIR_ENV]: '/another/chat' }
inheritedEnv: { [NATIVE_CHAT_SCRATCH_DIR_ENV]: '/another/chat' }
})
const resolved = await launch
expect(resolved.args).toEqual(['agent', 'stdio'])
expect(
resolveProviderChildEnv(resolved, { [NATIVE_CHAT_VISUALS_DIR_ENV]: '/another/chat' })[
NATIVE_CHAT_VISUALS_DIR_ENV
resolveProviderChildEnv(resolved, { [NATIVE_CHAT_SCRATCH_DIR_ENV]: '/another/chat' })[
NATIVE_CHAT_SCRATCH_DIR_ENV
]
).toBeUndefined()
expect(logger.warn).toHaveBeenCalledWith(
Expand All @@ -107,7 +116,7 @@ describe('ACP launch visuals', () => {
autoupdate: false,
skills: { paths: [SKILL.skillsRoot] }
})
expect(launch.env[NATIVE_CHAT_VISUALS_DIR_ENV]).toBe(FOLDER)
expect(launch.env[NATIVE_CHAT_SCRATCH_DIR_ENV]).toBe(FOLDER)
})

// OMP's settings layers (global, profile, project, overlays) replace lists, so any config of
Expand All @@ -119,7 +128,7 @@ describe('ACP launch visuals', () => {
}).launch
expect(launch.args).toEqual(['acp', '--plugin-dir', SKILL.pluginDir])
expect(launch.env.PI_CONFIG_FILES).toBe('/user/overlay.yml')
expect(launch.env[NATIVE_CHAT_VISUALS_DIR_ENV]).toBe(FOLDER)
expect(launch.env[NATIVE_CHAT_SCRATCH_DIR_ENV]).toBe(FOLDER)
})

it('still starts the chat when the skill cannot be prepared', async () => {
Expand All @@ -133,7 +142,8 @@ describe('ACP launch visuals', () => {
})
const resolved = await launch
expect(resolved.args).toEqual(['acp'])
expect(resolved.envToDelete).toContain(NATIVE_CHAT_VISUALS_DIR_ENV)
expect(resolved.envToDelete).toContain(NATIVE_CHAT_SCRATCH_DIR_ENV)
expect(resolved.envToDelete).toContain(LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV)
expect(logger.warn).toHaveBeenCalledWith(
expect.stringContaining('could not be prepared'),
expect.anything()
Expand Down
2 changes: 1 addition & 1 deletion src/main/acp/acp-structured-launch-visuals.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import type { AcpLaunchSpec } from './acp-launch-specs'
import type { AcpVisualsSkillLaunch } from './acp-visuals-skill'

export type AcpLaunchVisualsDeps = {
/** Prepares a chat's inline-visuals folder; absent, no chat gets visuals. */
/** Prepares a chat's scratch folder for inline visuals; absent, no chat gets visuals. */
prepareVisuals?: PrepareNativeChatVisuals
logger?: StructuredAgentSessionLogger
}
Expand Down
9 changes: 6 additions & 3 deletions src/main/claude/claude-child-process-environment.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
import { CLAUDE_AUTH_ENV_VARS, applyClaudeEnvPatch } from '../claude-accounts/environment'
import { NATIVE_CHAT_VISUALS_DIR_ENV } from '../native-chat/native-chat-visuals-delivery'
import {
LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV,
NATIVE_CHAT_SCRATCH_DIR_ENV
} from '../native-chat/native-chat-visuals-delivery'

const CLAUDE_CHILD_SESSION_STAMP_ENV_KEYS = [
'CLAUDE_CODE_CHILD_SESSION',
Expand Down Expand Up @@ -70,8 +73,8 @@ export function buildClaudeChildProcessEnv(
}
}
}
// Only the launch names a chat's visuals folder: an inherited one belongs to another chat.
stripEnvKeys(env, [NATIVE_CHAT_VISUALS_DIR_ENV], platform)
// Only the launch names a chat's scratch folder: an inherited one belongs to another chat.
stripEnvKeys(env, [NATIVE_CHAT_SCRATCH_DIR_ENV, LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV], platform)
if (options.scrubConfiguredChildSessionStamps) {
return stripClaudeChildSessionStamps({ ...env, ...configuredEnv }, platform)
}
Expand Down
12 changes: 6 additions & 6 deletions src/main/claude/claude-structured-launch-visuals.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import type { AgentSessionJournalIdentity } from '../../shared/agent-session-jou
import { agentSessionRecordFixture } from '../native-chat/agent-session-record-test-fixture'
import { LOCAL_EXECUTION_HOST_ID } from '../../shared/execution-host'
import {
NATIVE_CHAT_VISUALS_DIR_ENV,
NATIVE_CHAT_SCRATCH_DIR_ENV,
type NativeChatVisualsLaunch
} from '../native-chat/native-chat-visuals-delivery'
import {
Expand All @@ -15,7 +15,7 @@ import {

const SESSION_ID = 'orca-session-visuals'
const VISUALS: NativeChatVisualsLaunch = {
folder: '/state/native-chat-visuals/abc',
folder: '/state/chat-scratch/abc',
skill: { pluginDir: '/app/native-chat-visuals', skillsRoot: '/app/native-chat-visuals/skills' }
}

Expand Down Expand Up @@ -60,7 +60,7 @@ describe('a Claude chat launch with inline visuals', () => {
expect(prepareVisuals).toHaveBeenCalledWith(SESSION_ID)
expect(resolved.options.plugins).toEqual([{ type: 'local', path: VISUALS.skill.pluginDir }])
expect(resolved.options.additionalDirectories).toEqual(['/shared/notes', VISUALS.folder])
expect(resolved.env?.[NATIVE_CHAT_VISUALS_DIR_ENV]).toBe(VISUALS.folder)
expect(resolved.env?.[NATIVE_CHAT_SCRATCH_DIR_ENV]).toBe(VISUALS.folder)
})

it.each([
Expand Down Expand Up @@ -91,18 +91,18 @@ describe('a Claude chat launch with inline visuals', () => {
})
expect(resolved.options).not.toHaveProperty('plugins')
expect(resolved.options.additionalDirectories).toEqual([VISUALS.folder])
expect(resolved.env?.[NATIVE_CHAT_VISUALS_DIR_ENV]).toBe(VISUALS.folder)
expect(resolved.env?.[NATIVE_CHAT_SCRATCH_DIR_ENV]).toBe(VISUALS.folder)
})

it('without a prepared folder, grants nothing and drops a folder inherited from another chat', async () => {
const resolved = await launch({
prepareVisuals: async () => null,
supports: async () => true,
env: { [NATIVE_CHAT_VISUALS_DIR_ENV]: '/state/native-chat-visuals/other-chat' }
env: { [NATIVE_CHAT_SCRATCH_DIR_ENV]: '/state/chat-scratch/other-chat' }
})
expect(resolved.options).not.toHaveProperty('plugins')
expect(resolved.options).not.toHaveProperty('additionalDirectories')
expect(resolved.env).not.toHaveProperty(NATIVE_CHAT_VISUALS_DIR_ENV)
expect(resolved.env).not.toHaveProperty(NATIVE_CHAT_SCRATCH_DIR_ENV)
})

it('never asks about the plugin flag on a host that delivers no visuals', async () => {
Expand Down
4 changes: 2 additions & 2 deletions src/main/claude/claude-structured-real-cli-visuals.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import type { AgentSessionJournalIdentity } from '../../shared/agent-session-jou
import { agentSessionRecordFixture } from '../native-chat/agent-session-record-test-fixture'
import { claudeProviderHandle } from '../../shared/agent-session-provider-handle-encoding'
import { createNativeChatVisualsDelivery } from '../native-chat/native-chat-visuals-delivery'
import { nativeChatVisualsFolderFor } from '../native-chat/native-chat-visuals-folder'
import { nativeChatScratchFolderFor } from '../native-chat/native-chat-scratch-folder'
import { NATIVE_CHAT_VISUALS_SKILL_NAME } from '../native-chat/native-chat-visuals-skill-location'
import { createClaudeCliFlagSupport } from './claude-cli-flag-support'
import { readClaudeInit } from './claude-structured-init-proof'
Expand Down Expand Up @@ -75,7 +75,7 @@ describe.skipIf(!realClaudeAvailable)(suiteTitle, () => {
try {
await mkdir(cwd, { recursive: true })
const launch = await resolveLaunch({ identity })
const folder = nativeChatVisualsFolderFor(stateDirectory, SESSION_ID)
const folder = nativeChatScratchFolderFor(stateDirectory, SESSION_ID)
expect(launch.options.additionalDirectories).toEqual([folder])
expect(launch.options.plugins).toHaveLength(1)
await adapter.acquire({
Expand Down
7 changes: 5 additions & 2 deletions src/main/codex/codex-structured-launch-resolution.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,10 @@ import type { AgentSessionRecord } from '../../shared/agent-session-record'
import type { AgentSessionProviderHandleLink } from '../../shared/agent-session-provider-handle'
import { LOCAL_EXECUTION_HOST_ID } from '../../shared/execution-host'
import { codexProviderHandle } from '../../shared/agent-session-provider-handle-encoding'
import { NATIVE_CHAT_VISUALS_DIR_ENV } from '../native-chat/native-chat-visuals-delivery'
import {
LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV,
NATIVE_CHAT_SCRATCH_DIR_ENV
} from '../native-chat/native-chat-visuals-delivery'

const { isWindowsProcessStartTimeAvailable } = vi.hoisted(() => ({
isWindowsProcessStartTimeAvailable: vi.fn(() => true)
Expand Down Expand Up @@ -171,7 +174,7 @@ describe('codex structured launch resolution', () => {
approvalsReviewer: 'user'
},
env: { CODEX_HOME: '/home/work/.codex' },
envToDelete: [NATIVE_CHAT_VISUALS_DIR_ENV]
envToDelete: [NATIVE_CHAT_SCRATCH_DIR_ENV, LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV]
})
})

Expand Down
8 changes: 6 additions & 2 deletions src/main/codex/codex-structured-launch-resolution.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ import { codexStructuredPermissionPolicy } from './codex-structured-permission-p
import { resolvePinnedCodexRolloutProof } from './codex-pinned-rollout-proof'
import { codexStructuredLaunchArgs } from './codex-structured-launch-args'
import {
NATIVE_CHAT_VISUALS_DIR_ENV,
LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV,
NATIVE_CHAT_SCRATCH_DIR_ENV,
withNativeChatVisualsEnv
} from '../native-chat/native-chat-visuals-delivery'

Expand Down Expand Up @@ -109,7 +110,10 @@ export function codexStructuredLaunchPart(
visuals
),
// Without visuals, a folder Orca itself inherited (started from a chat) names another chat's.
inheritedEnvToDelete: visuals ? [] : [NATIVE_CHAT_VISUALS_DIR_ENV]
inheritedEnvToDelete: [
...(visuals ? [] : [NATIVE_CHAT_SCRATCH_DIR_ENV]),
LEGACY_NATIVE_CHAT_VISUALS_DIR_ENV
]
}
}
}
2 changes: 1 addition & 1 deletion src/main/codex/codex-structured-real-cli-visuals.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ describe.skipIf(!enabled)('Codex real app-server chat visuals', () => {
const codexHome = join(base, 'codex-home')
const cwd = join(base, 'workspace')
const userRoot = join(base, 'user-root')
const folder = join(base, 'state', 'native-chat-visuals', 'chat')
const folder = join(base, 'state', 'chat-scratch', 'chat')
for (const dir of [codexHome, cwd, folder]) {
mkdirSync(dir, { recursive: true })
}
Expand Down
2 changes: 1 addition & 1 deletion src/main/codex/codex-structured-session-state.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ export type CodexStructuredLaunch = {
/** The child's sealed environment, and the inherited keys it must not keep. */
env?: Record<string, string>
envToDelete?: readonly string[]
/** This chat's visuals folder and skill; absent when the chat has no visuals. */
/** This chat's scratch folder and visuals skill; absent when the chat has no visuals. */
visuals?: NativeChatVisualsLaunch
}

Expand Down
10 changes: 5 additions & 5 deletions src/main/codex/codex-structured-visuals.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { describe, expect, it, vi } from 'vitest'
import {
NATIVE_CHAT_VISUALS_DIR_ENV,
NATIVE_CHAT_SCRATCH_DIR_ENV,
type NativeChatVisualsLaunch
} from '../native-chat/native-chat-visuals-delivery'
import { CodexAppServerRequestError } from './codex-app-server-request-error'
Expand All @@ -21,7 +21,7 @@ import {
import { codexStructuredPermissionPolicy } from './codex-structured-permission-policy'

const VISUALS: NativeChatVisualsLaunch = {
folder: '/state/native-chat-visuals/abc',
folder: '/state/chat-scratch/abc',
skill: { pluginDir: '/app/native-chat-visuals', skillsRoot: '/app/native-chat-visuals/skills' }
}
const MANUAL = codexStructuredPermissionPolicy('ask')
Expand Down Expand Up @@ -209,18 +209,18 @@ describe('a Codex chat acquisition with visuals', () => {
...MANUAL,
config: { 'sandbox_workspace_write.writable_roots': ['/home/me/scratch', VISUALS.folder] }
})
expect(connection.launch.env?.[NATIVE_CHAT_VISUALS_DIR_ENV]).toBe(VISUALS.folder)
expect(connection.launch.env?.[NATIVE_CHAT_SCRATCH_DIR_ENV]).toBe(VISUALS.folder)
}
})

it('opens the thread exactly as before for a chat without visuals', async () => {
const codex = fakeCodex()
await acquired(codex, { env: { [NATIVE_CHAT_VISUALS_DIR_ENV]: '/other' } })
await acquired(codex, { env: { [NATIVE_CHAT_SCRATCH_DIR_ENV]: '/other' } })
const connection = codex.connections[0]!
const methods = connection.calls.map((call) => call.method)
expect(methods[0]).toBe('thread/start')
expect(methods).not.toContain('skills/extraRoots/set')
expect(connection.calls[0]?.params).not.toHaveProperty('config')
expect(connection.launch.env).not.toHaveProperty(NATIVE_CHAT_VISUALS_DIR_ENV)
expect(connection.launch.env).not.toHaveProperty(NATIVE_CHAT_SCRATCH_DIR_ENV)
})
})
Loading
Loading