Skip to content
Merged
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
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[![CI](https://github.com/SingularityCoLabs/parallax/actions/workflows/ci.yml/badge.svg)](https://github.com/SingularityCoLabs/parallax/actions/workflows/ci.yml)
[![Release](https://github.com/SingularityCoLabs/parallax/actions/workflows/publish.yml/badge.svg)](https://github.com/SingularityCoLabs/parallax/actions/workflows/publish.yml)
[![npm](https://img.shields.io/npm/v/%40singularitycolabs%2Fparallax?label=npm%20next)](https://www.npmjs.com/package/@singularitycolabs/parallax)
[![npm](https://img.shields.io/npm/v/%40singularitycolabs%2Fparallax?label=npm%20latest)](https://www.npmjs.com/package/@singularitycolabs/parallax)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

A secure, extensible **agent runtime** with a CLI as its first interface. The model
Expand Down Expand Up @@ -145,7 +145,7 @@ the history carries over to the new model:
> /models list models for the current provider (with price/context)
> /provider openai switch provider (uses its default model)
> /model anthropic/claude-sonnet-4-6 switch provider + model in one step
> /model open the interactive model picker
> /model (or /m) choose a provider, then choose its model
> /tools list the available agent tools
> /theme light switch the color theme (toggles with no arg)
> /mode plan set permission mode (or /plan, /workspace, /read-only, /bypass)
Expand Down
24 changes: 15 additions & 9 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,15 @@
Parallax uses two release paths in
[`publish.yml`](../.github/workflows/publish.yml):

| Branch | Trigger | npm dist-tag | Purpose |
| ------------- | ------------------------ | ------------ | --------------------- |
| `main` | Successful main CI run | `next` | Public beta releases |
| `development` | Manual workflow dispatch | `dev` | Development snapshots |
| Branch | Trigger | npm dist-tag | Purpose |
| ------------- | ------------------------ | ------------ | ----------------------- |
| `main` | Successful main CI run | `latest` | Public pre-1.0 releases |
| `development` | Manual workflow dispatch | `dev` | Development snapshots |

While Parallax is pre-1.0, the newest public build is intentionally published as
`latest`, including beta versions. The legacy `next` tag is not advanced by the
current workflow; use the plain package name or `@latest` when installing and
verifying a release.

Daily work belongs on `development`. Promote tested work to `main` with a pull
request. Do not create npm versions, Git tags, or GitHub Releases for normal beta
Expand Down Expand Up @@ -47,8 +52,8 @@ After choosing the version, the workflow:
3. Creates a generated `chore(release): v<version> [skip ci]` commit when the
manifest version changed.
4. Atomically pushes the release commit and matching `v<version>` tag.
5. Publishes prereleases to npm `next`, or stable versions to npm `latest`, with
provenance through trusted publishing.
5. Publishes the selected pre-1.0 release to npm `latest`, with provenance
through trusted publishing.
6. Creates the matching GitHub Release and generated release notes.

The atomic Git push prevents npm publication if another main update races with
Expand Down Expand Up @@ -90,9 +95,9 @@ Verify the completed release:

```bash
npm dist-tag ls @singularitycolabs/parallax
npm view @singularitycolabs/parallax@next version gitHead
npm view @singularitycolabs/parallax@latest version gitHead
gh release list --repo SingularityCoLabs/parallax --limit 5
npx --yes @singularitycolabs/parallax@next --version
npx --yes @singularitycolabs/parallax@latest --version
```

## Starting a new release line
Expand All @@ -116,7 +121,8 @@ main merges automatically advance to `0.2.0-beta.1`, `0.2.0-beta.2`, and so on.

To publish a stable release, deliberately set an unpublished stable version such
as `0.2.0` on `development`, verify it, and promote it through the same pull
request flow. Stable releases use npm `latest` and create a normal GitHub Release.
request flow. Stable releases continue using npm `latest` and create a normal
GitHub Release instead of a prerelease.

## Manually publishing `development`

Expand Down
3 changes: 2 additions & 1 deletion src/cli/replCommands.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ export function parseCommand(line: string): ReplCommand {
return { kind: 'models', ...(arg !== undefined ? { arg } : {}) };
case 'provider':
return { kind: 'provider', ...(arg !== undefined ? { arg } : {}) };
case 'm':
case 'model':
return { kind: 'model', ...(arg !== undefined ? { arg } : {}) };
default:
Expand Down Expand Up @@ -120,7 +121,7 @@ export function formatModels(providerId: string, currentModel?: string): string
export function formatHelp(): string {
return [
'commands:',
' /model [id] switch model, or open the picker (e.g. /model claude-sonnet-4-6)',
' /model | /m [id] switch model; bare command opens the provider/model picker in the TUI',
' /model <prov>/<id> switch provider + model (e.g. /model openai/gpt-4o)',
' /provider <id> switch provider, using its default model',
' /models [provider] list models for the current (or named) provider',
Expand Down
56 changes: 40 additions & 16 deletions src/cli/tui/App.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import {
readUpdateCache,
refreshUpdateInfo,
resolveApiKey,
sanitizeApiKey,
saveCredential,
saveLocalConfig,
upgradeCommand,
Expand Down Expand Up @@ -96,6 +97,10 @@ export function App(props: AppProps): React.ReactElement {
const [dialogOpen, setDialogOpen] = useState(false);
const [dialogProviders, setDialogProviders] = useState<ProviderInfo[]>([]);
const [dialogInitialProvider, setDialogInitialProvider] = useState<string | undefined>(undefined);
const [dialogInitialModel, setDialogInitialModel] = useState<string | undefined>(undefined);
const [dialogInitialStep, setDialogInitialStep] = useState<'provider' | 'model' | undefined>(
undefined,
);
const [sessionKeys, setSessionKeys] = useState<Record<string, string>>({});
// "Update available" banner data: read the local cache immediately, then do a
// best-effort network refresh. Both are non-blocking and never throw.
Expand All @@ -119,23 +124,36 @@ export function App(props: AppProps): React.ReactElement {
const info = getProvider(id);
if (!info) return false;
if (info.wire === 'fake') return true; // the fake provider needs no key
return Boolean(sessionKeys[id] ?? resolveApiKey(id));
return Boolean(sanitizeApiKey(sessionKeys[id] ?? resolveApiKey(id)));
},
[sessionKeys],
);

/**
* Open the `/model` overlay, snapshotting the catalog so it can't shift. A
* `fake`/empty provider is treated as "no preset" so the dialog opens on the
* provider list rather than jumping into the offline stub's model step.
* Open the `/model` overlay, snapshotting the catalog so it can't shift. The
* bare command starts at the provider list with the active provider selected;
* recovery from a direct switch can still jump to that provider/model/key. A
* `fake`/empty provider is treated as "no preset" so it never shortcuts into
* the offline stub's model step.
*/
const openDialog = useCallback((initialProvider?: string) => {
setDialogProviders(listProviders());
setDialogInitialProvider(
initialProvider && initialProvider !== 'fake' ? initialProvider : undefined,
);
setDialogOpen(true);
}, []);
const openDialog = useCallback(
(
initial: {
provider?: string;
model?: string;
step?: 'provider' | 'model';
} = {},
) => {
setDialogProviders(listProviders());
setDialogInitialProvider(
initial.provider && initial.provider !== 'fake' ? initial.provider : undefined,
);
setDialogInitialModel(initial.model);
setDialogInitialStep(initial.step);
setDialogOpen(true);
},
[],
);

const pushSystem = useCallback((text: string) => {
setSystemLines((prev) => [...prev.slice(-40), ...text.split('\n')]);
Expand Down Expand Up @@ -200,7 +218,10 @@ export function App(props: AppProps): React.ReactElement {
// No key on this path — offer the dialog to enter one, preset to the
// provider the user asked for.
pushSystem(`${sel.provider} needs an API key. Opening /model to configure it…`);
openDialog(sel.provider);
openDialog({
provider: sel.provider,
...(sel.model !== undefined ? { model: sel.model } : {}),
});
return;
}
pushSystem(`Could not switch: ${err instanceof Error ? err.message : String(err)}`);
Expand Down Expand Up @@ -247,8 +268,9 @@ export function App(props: AppProps): React.ReactElement {
return;
case 'model': {
if (!command.arg) {
// Bare `/model` opens the interactive picker (OpenCode-style).
openDialog(provider);
// Bare `/model` and `/m` expose the complete provider → model path,
// with the current provider highlighted rather than skipped.
openDialog({ provider, model, step: 'provider' });
return;
}
await switchTo(parseModelSelector(command.arg, provider));
Expand Down Expand Up @@ -345,7 +367,7 @@ export function App(props: AppProps): React.ReactElement {
// No usable model yet — send them to the picker instead of a dead turn.
if (needsSetup) {
pushSystem('Choose a model first — opening /model.');
openDialog(provider);
openDialog({ provider });
return;
}
await submitTurn(line);
Expand All @@ -358,7 +380,7 @@ export function App(props: AppProps): React.ReactElement {
useEffect(() => {
if (needsSetup && introDone && !autoOpened && !dialogOpen) {
setAutoOpened(true);
openDialog(provider);
openDialog({ provider });
}
}, [needsSetup, introDone, autoOpened, dialogOpen, openDialog, provider]);

Expand Down Expand Up @@ -465,6 +487,8 @@ export function App(props: AppProps): React.ReactElement {
theme={theme}
providers={dialogProviders}
{...(dialogInitialProvider ? { initialProviderId: dialogInitialProvider } : {})}
{...(dialogInitialModel ? { initialModelId: dialogInitialModel } : {})}
{...(dialogInitialStep ? { initialStep: dialogInitialStep } : {})}
hasKey={hasKey}
onSubmit={onDialogSubmit}
onCancel={() => setDialogOpen(false)}
Expand Down
20 changes: 18 additions & 2 deletions src/cli/tui/components/ApprovalPrompt.tsx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import React from 'react';
import { Box, Text } from 'ink';
import SelectInput from 'ink-select-input';
import SelectInput, { type IndicatorProps, type ItemProps } from 'ink-select-input';
import type { ApprovalDecision } from '../../../protocol/index.ts';
import { DiffView } from './DiffView.tsx';
import { type Theme } from '../theme.ts';
Expand Down Expand Up @@ -32,6 +32,17 @@ export function ApprovalPrompt({
theme: Theme;
onDecision: (decision: ApprovalDecision) => void;
}): React.ReactElement {
const ThemedIndicator = ({ isSelected = false }: IndicatorProps): React.ReactElement => (
<Box marginRight={1}>
<Text color={isSelected ? theme.selection : theme.subtle}>{isSelected ? '❯' : ' '}</Text>
</Box>
);
const ThemedItem = ({ isSelected = false, label }: ItemProps): React.ReactElement => (
<Text color={isSelected ? theme.selection : theme.text} bold={isSelected}>
{label}
</Text>
);

return (
<Box
flexDirection="column"
Expand All @@ -53,7 +64,12 @@ export function ApprovalPrompt({
{request.diffPreview !== undefined && <DiffView diff={request.diffPreview} theme={theme} />}

<Box marginTop={1}>
<SelectInput items={CHOICES} onSelect={(item: Choice) => onDecision(item.value)} />
<SelectInput
items={CHOICES}
indicatorComponent={ThemedIndicator}
itemComponent={ThemedItem}
onSelect={(item: Choice) => onDecision(item.value)}
/>
</Box>
</Box>
);
Expand Down
64 changes: 49 additions & 15 deletions src/cli/tui/components/ModelDialog.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,10 @@ export interface ModelDialogProps {
providers: ProviderInfo[];
/** Preselect this provider (the desired one when launching unconfigured). */
initialProviderId?: string;
/** Preserve a directly requested model while collecting a missing API key. */
initialModelId?: string;
/** Start on the provider list without discarding the active-provider highlight. */
initialStep?: 'provider' | 'model';
/** Whether a key already resolves for a provider (env / creds / session). */
hasKey: (providerId: string) => boolean;
onSubmit: (selection: ModelSelection) => void;
Expand Down Expand Up @@ -80,21 +84,41 @@ export function ModelDialog({
theme,
providers,
initialProviderId,
initialModelId,
initialStep,
hasKey,
onSubmit,
onCancel,
}: ModelDialogProps): React.ReactElement {
// Preselecting a provider jumps past the provider list: to the model step if
// it already has a key, or straight to key entry if it doesn't. Otherwise we
// start at the provider list.
// A preset can either be highlighted on the provider step (bare `/model`) or
// jump to model/key recovery (a direct switch that discovered a missing key).
const preset = initialProviderId
? providers.find((p) => p.id === initialProviderId && p.supported)
: undefined;
const presetNeedsKey = preset !== undefined && !hasKey(preset.id);
const beginAtProvider = initialStep === 'provider' || preset === undefined;
const presetIndex = preset ? providers.findIndex((p) => p.id === preset.id) : 0;
const presetModel = initialModelId ?? preset?.defaultModel ?? '';
const presetModelIndex = preset?.models.indexOf(presetModel) ?? -1;
const presetCustomIndex =
preset?.models.filter((model) => matches(model, presetModel)).length ?? 0;
const beginAtModel = !beginAtProvider && !presetNeedsKey;

const [step, setStep] = useState<Step>(preset ? (presetNeedsKey ? 'key' : 'model') : 'provider');
const [filter, setFilter] = useState('');
const [selected, setSelected] = useState(0);
const [step, setStep] = useState<Step>(
beginAtProvider ? 'provider' : presetNeedsKey ? 'key' : 'model',
);
const [filter, setFilter] = useState(
beginAtModel && presetModel !== '' && presetModelIndex < 0 ? presetModel : '',
);
const [selected, setSelected] = useState(
beginAtProvider
? Math.max(0, presetIndex)
: beginAtModel
? presetModelIndex >= 0
? presetModelIndex
: presetCustomIndex
: 0,
);
const [providerId, setProviderId] = useState(preset?.id ?? '');
const [keyText, setKeyText] = useState('');
// Default ON: a key entered here is saved to the 0600 credentials store so the
Expand All @@ -103,9 +127,7 @@ export function ModelDialog({
const [hint, setHint] = useState('');
// The model chosen while we detour through the key step (its default when we
// jumped straight to key entry for a preset provider).
const [pendingModel, setPendingModel] = useState(
presetNeedsKey ? (preset?.defaultModel ?? '') : '',
);
const [pendingModel, setPendingModel] = useState(presetModel);

const provider = useMemo(
() => providers.find((p) => p.id === providerId),
Expand All @@ -125,9 +147,14 @@ export function ModelDialog({
// non-matching filter becomes an explicit "use what I typed" row.
const allowCustomModel = filter.trim() !== '' && !modelRows.some((m) => m === filter.trim());

const resetList = (): void => {
setFilter('');
setSelected(0);
const focusModel = (p: ProviderInfo | undefined, preferredModel?: string): void => {
const candidate = preferredModel ?? p?.defaultModel ?? '';
const index = p?.models.indexOf(candidate) ?? -1;
const customIndex = p?.models.filter((model) => matches(model, candidate)).length ?? 0;
// An arbitrary/custom model is represented by the synthetic filtered row.
setFilter(candidate !== '' && index < 0 ? candidate : '');
setSelected(index >= 0 ? index : customIndex);
setPendingModel(candidate);
setHint('');
};

Expand All @@ -138,7 +165,7 @@ export function ModelDialog({
}
setProviderId(p.id);
setStep('model');
resetList();
focusModel(p, p.id === preset?.id ? presetModel : p.defaultModel);
};

const chooseModel = (model: string): void => {
Expand Down Expand Up @@ -168,12 +195,19 @@ export function ModelDialog({
if (step === 'provider') return onCancel();
if (step === 'model') {
setStep('provider');
resetList();
setFilter('');
setSelected(
Math.max(
0,
providers.findIndex((p) => p.id === providerId),
),
);
setHint('');
return;
}
setStep('model'); // from key step
setKeyText('');
resetList();
focusModel(provider, pendingModel);
return;
}

Expand Down
Loading