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
73 changes: 31 additions & 42 deletions docs/system-specs/modules/learn-cron-dashboard.md
Original file line number Diff line number Diff line change
Expand Up @@ -929,50 +929,39 @@ join rows 1–2b's provenance gate.

**The picker says which agents the folder supplied.** A project row carries
`scope: "project"` from the roster endpoint, and `AgentSelector` renders a
`from this folder` marker off that field — NOT off `source`, which reads
`folder agent` marker off that field — NOT off `source`, which reads
`kirocrew` on a project row exactly as it does on a configured one, so without
this a folder-supplied agent was visually identical to a global one and nobody
could anticipate which picks vanish when the directory is cleared. The
`overrides global` chip covers only COLLIDING rows, a strict subset.

**A reset selection is announced, not just performed.** When a directory change
clears an agent the new folder cannot resolve, the form names the cleared agent
beside the Agent field. The reset itself is correct — saving a name the folder
cannot resolve would fire the default agent silently — but doing it without
acknowledgment meant a deliberate pick disappeared between a keystroke and
Save. **The announcement has to OUTLIVE the roster settling, which is a
constraint on the effect rather than on the copy.** Emptying the field runs the
clear-on-unbind branch twice — once when `projectPath` empties, then again when
the 250ms-debounced mirror settles and `enabled: !!debouncedProjectPath` turns
the roster query off, moving `projectAgentsData` to `undefined` and so changing a
dependency. The second run sees the agent the first already cleared, computes
"nothing was cleared", and would write the reset name back to `''` — erasing its
own notice after ~250ms. The branch is therefore guarded to act on the TRANSITION
into the empty state (`unbindHandledRef`), re-armed by any bound path so a later
clear still announces itself. A test that reads the notice synchronously cannot
see this: it passes against the erasing version, which is why the form's
regressions read it AFTER the debounce.

**A reset a path EDIT caused is undone when the finished path defines the name
again.** The debounce above only protects a path typed faster than 250ms;
hand-editing a bound job's directory pauses longer, so an intermediate path
becomes a roster identity of its own — and `GET /api/agents?project_path=`
answers an unusable path with HTTP 200 and the configured agents alone, so that
roster legitimately lacks the pick and the reconcile clears it. Clearing on what
is known is right; leaving it cleared once the FINISHED path loads a roster that
DOES define the name is not, and made every path edit on a bound job force a
re-pick. The reconcile therefore remembers the name it took away
(`editClearedAgentRef`) and restores it when a later settled roster resolves it
and the user has not chosen since — restoring needs no judgement about whether a
path was "half typed", a question the endpoint cannot answer anyway since an
unusable path and a usable one with no agents are the same 200. Two bounds keep
this from overriding an operator: a deliberate pick drops the remembered name
(`pickAgent`), and so does emptying the field, whose own clear is an ended
gesture with no later roster to land against and stands announced. While a
restore is pending the notice is WITHHELD from the `''` write rather than erased
— the reset it describes is still in force, and a further intermediate settle
erasing it is the same defect as the double-run above, leaving an operator whose
finished path never does define the name with no acknowledgment at all.
could tell which picks depend on the directory. The accent-toned `folder's version`
chip covers only COLLIDING rows, a strict subset, and its detail line names the
definition that runs and that picking it changes nothing saved: "This job runs the folder's {{name}}. Your saved one is unchanged."
The picker's copy avoids "project", "global" and `.kiro/agents/`: a first-time
reader of the UX lane's blind read did not know those terms.
Only the roster's `scope: "project"` rows join the catalog the form already
holds; its global half is consulted for one fact only, that the server dropped
an alias whose template the folder declares, and the form drops that catalog
member row too (`JobForm` `effectiveAgents`).

**A directory change never rewrites the agent pick; Save decides.** Whether a
name resolves under a folder is answered by the resolver dispatch uses, and the
picker catalogs cannot stand in for it: the project roster endpoint omits
installed templates, and the global catalog omits runtime-owned templates the
backend still runs, so absence from either proves nothing. The form therefore
keeps the selected name across a directory switch, an emptied field and any
roster loading or failure gap, and sends it on Save. The save-time half of the
twice-checked rule (`_agent_unresolvable_response`) refuses a name the bound
folder cannot resolve with a 400 (`code: "unknown_agent"`) naming the agent and
folder, which the form shows under the Agent picker (the Schedule page's vertical layout; the compact row keeps it form-wide) with "Pick an agent from this folder." when a directory is set, cleared by the next pick; every fire re-checks it. A form-side guess that
cleared picks on catalog absence discarded valid bindings and then saved the
default agent in their place, which is the silent substitution this feature
exists to prevent.

**The directory picker joins the schedule dialog's modal layer.** In this form
it uses a modal Radix Popover, with a viewport-positioned portal outside the
translated dialog content. Pointer input, focus and dismissal belong to the
picker while it is open: a directory icon or row can be selected even where it
extends beyond the dialog, without closing the dialog or discarding its draft.
Standalone and non-Radix-modal ProjectPicker callers retain their own layer.

**Session reuse tracks which definition won.** A persistent job reuses its
session, so `_cron_session_binding` records the resolved identity — the folder,
Expand Down
1 change: 1 addition & 0 deletions website/scripts/gen-pseudolocale.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ const PRESERVE = [
/<[^>]+>/g, // markup, and the URL-shaped `<…>` values in this catalog
/\$t\([^)]*\)/g, // i18next nesting
/https?:\/\/\S+/g, // urls
/\/Users\/you\/projects\/myrepo/g, // canonical project-directory example path
]

/** The masking sentinel, as a non-global regex so `.test()` carries no `lastIndex`. */
Expand Down
1 change: 1 addition & 0 deletions website/scripts/lib/render-scan.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,7 @@ export const ALWAYS_LATIN = [
*/
export const PRESERVED_REGIONS = [
/https?:\/\/\S+/g, // urls — may CONTAIN a <…> or {{…}} region, so strip first
/\/Users\/you\/projects\/myrepo/g, // canonical project-directory example path
/\{\{[^}]*\}\}/g, // i18next interpolation
/\$t\([^)]*\)/g, // i18next nesting
/<[^>]+>/g, // markup, and the URL-shaped <…> values in this catalog
Expand Down
14 changes: 11 additions & 3 deletions website/src/api/client/agents.ts
Original file line number Diff line number Diff line change
Expand Up @@ -264,10 +264,18 @@ export function createAgentsEndpoints({ post, put, del, j, jfetch: fetch, sessio
// slots sit on different projects, so project-scoped agents silently
// vanish from the picker. Surfaces with no slot context (Channels,
// Schedule) pass nothing and keep the global-only view.
kirocrewAgents: (sessionKey?: string) =>
fetch('/api/agents', {
//
// `projectPath` is the raw-path fallback (Decision 1, cron project agents):
// a surface with no live slot (e.g. the Schedule page's job form) can still
// ask for a project's agents by passing the path directly. The server only
// honors it when sessionKey resolved to no project — a real slot's own
// project always wins, so this cannot override a live session's scope.
kirocrewAgents: (sessionKey?: string, projectPath?: string) => {
const qs = projectPath ? '?project_path=' + encodeURIComponent(projectPath) : ''
return fetch('/api/agents' + qs, {
headers: sessionKey ? { 'X-Session-Key': sessionKey } : { ..._sk },
}).then(j),
}).then(j)
},
/** The model a new session on this Kiro Crew agent would run on. Empty
* `agent` resolves the configured default agent; `app` adds the owning
* app's own model setting. */
Expand Down
99 changes: 95 additions & 4 deletions website/src/components/AgentSelector.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,14 @@ export interface KiroCrewAgent {
* older payloads predate the field, and it falls back to `description`. */
triggers?: string
source: string
/** Which roster half this row came from: `'global'` for a configured agent,
* `'project'` for one declared by `<project>/.kiro/agents`. Optional because
* a caller that never passes `project_path` has no project half to
* distinguish, only catalog rows carry it, and older payloads predate the
* field. Distinct from `source`, which names the row's PROVENANCE (kirocrew,
* package, app) and reads `'kirocrew'` on a project row — the two are not
* interchangeable. */
scope?: string
/** Default session color (#rrggbb hex) applied to new sessions using this
* agent. Empty or absent means no agent color. */
session_color?: string
Expand All @@ -43,8 +51,6 @@ export interface KiroCrewAgent {
* members only. A member and a template can share a `name`, so a consumer
* that offers both must key on (selection_kind, name), never on the name. */
selection_kind?: 'member' | 'template'
/** `global` or `project`; only catalog rows carry it. */
scope?: string
}

/** The label a roster surface shows for a crew: its display name when one is
Expand Down Expand Up @@ -105,6 +111,24 @@ interface Props {
* keep the flat rendering they had, whatever their rows carry.
*/
groupByKind?: boolean
/**
* Names in `agents` where a PROJECT agent displaced a same-named configured
* one, so the row can say so. Present only on a surface that merges a
* project's roster into the global one (Schedule's job form); absent
* everywhere else, where no collision is representable.
*
* The list holds ONE row per name — the project one, because that is what
* dispatch resolves inside a bound folder. Without this marker the user sees
* a `project` badge and a global agent that has silently disappeared from
* the list, with nothing connecting the two. "This is a project agent" and
* "this project agent took over a configured agent's name" are different
* facts, and only the second explains the absence.
*
* A Set rather than a flag on the agent objects: those mirror a server
* payload, and a synthetic field on them would be indistinguishable from one
* the API actually sends.
*/
shadowedGlobals?: Set<string>
}

/**
Expand All @@ -123,7 +147,7 @@ interface Props {
* Popover has no option semantics of its own, so the listbox ARIA and roving
* focus come from `useListboxKeyboard`, unchanged.
*/
export default function AgentSelector({ agents, defaultAgent, value, onChange, modal = false, rosterFailure, groupByKind = false }: Props) {
export default function AgentSelector({ agents, defaultAgent, value, onChange, modal = false, rosterFailure, groupByKind = false, shadowedGlobals }: Props) {
const provider = useProvider()
const [open, setOpen] = useState(false)
const [filter, setFilter] = useState('')
Expand Down Expand Up @@ -282,8 +306,75 @@ export default function AgentSelector({ agents, defaultAgent, value, onChange, m
{a.source}
</SourceBadge>
)}
{/* `scope`, not `source` (UX Review): the server tags a
project row `scope: 'project'` but `source` reads
'kirocrew' on it exactly as it does on a configured one,
so a project-supplied agent was visually identical to a
global one and a user could not tell which picks would
vanish when the directory was cleared. The `overrides
global` chip only ever covered COLLIDING rows, which is a
strict subset. Suppressed on a shadowed row: `overrides
global` already entails a project agent (only a project
definition can displace a same-named global one), so both
chips together are redundant and, three-abreast in the
400px popover, they starve the name to "releas…" on the
exact collision rows this picker exists to disambiguate.
Dropping the weaker, implied chip returns that width to
the name (UX Review span=fc70ac00dcd8). */}
{a.scope === 'project' && !shadowedGlobals?.has(a.name) && (
<span className="px-1.5 py-[1px] rounded-full text-[10px] font-bold bg-bg-elevated text-muted border border-border shrink-0">
{i18nT('components.agentSelector.project_agent')}
</span>
)}
{/* Accent-toned: distinct from the muted source pills, which a
blind reader took for one more origin label like `kirocrew`,
but not warning-toned, which read as "picking this overwrites
my saved agent". Picking it only chooses which definition this
one job runs (UX Review). */}
{shadowedGlobals?.has(a.name) && (
<span className="px-1.5 py-[1px] rounded-full text-[10px] font-bold bg-accent-subtle text-accent border border-accent shrink-0">
{i18nT('components.agentSelector.overrides_global')}
</span>
)}
</div>
<span className="text-[11px] text-muted truncate">{a.description || provider.resolveAgentTemplate(a)}</span>
{/* A shadowed row spends this line on the override instead of
the usual description. It is not a nicety: the badge above
is a 10px chip whose only explanation was a `title`, and a
native tooltip needs a mouse resting precisely on that chip
— no hover exists on touch, and the whole point of the
marker is that a user who cannot find their configured
agent learns why. The line is free here, because a project
row has no description of its own and would otherwise
repeat the template name the row already resolves to.

It names the winner -- this folder's agent, not the user's
saved one -- because a line that only said a project agent
"runs instead" left a blind reader unsure which same-named
definition the job would get (UX Review). It says "folder"
and "saved" rather than "project", "global" or the
`.kiro/agents/` path, which a later blind reader did not
understand (UX Review). The name sits mid-sentence rather
than leading it: the row title directly above already shows
it, and this line wraps rather than truncating. */}
{/* A shadowed row renders the FULL hint as body text and is
allowed to wrap, where every other row truncates. Two
reasons it earns the extra line: the explanation is the
only thing telling a user why their configured agent is
not the one running, and this string is translated in
every catalog, so wrapping it here gives non-English users
the same reassurance rather than an English-only clause
bolted onto the shorter detail string. */}
<span
className={
shadowedGlobals?.has(a.name)
? 'text-[11px] text-muted'
: 'text-[11px] text-muted truncate'
}
>
{shadowedGlobals?.has(a.name)
? i18nT('components.agentSelector.overrides_global_hint', { name: a.name })
: a.description || provider.resolveAgentTemplate(a)}
</span>
</div>
{isCurrent && <span className="text-accent text-[11px] ml-auto shrink-0"><Check className="lucide-inline" /></span>}
</Btn>
Expand Down
Loading
Loading