diff --git a/apps/computer/local-daemon/README.md b/apps/computer/local-daemon/README.md index da2de5d4f..63f5e43c5 100644 --- a/apps/computer/local-daemon/README.md +++ b/apps/computer/local-daemon/README.md @@ -151,6 +151,14 @@ model. Daemon rereads the status, which carries what the phase reserved or freed (pool use, placement, models unloaded first), and applies the job's line on top; later lines of the phase update that snapshot without another read. +- Error causes. `library status` keeps only a failed row's `code` and + `detail`; the `cause` and `path` of a `GATEWAY_REGISTRATION_FAILED` reach + the Daemon only on the job's error line (`GATEWAY_HOME_NOT_PRIVATE`: the + gateway's private folder at `path` has another owner). The Daemon keeps them + per model and puts them back on that row in every read while it still fails + with that code; the model's next accepted job, or a row that moved on, + drops them. They live in memory, so after a Daemon restart the row shows + only its code. - Pi. When the loaded models change, the Daemon asks the Runtime monitor for a full discovery, so TeamHub sees Pi's new model list. Each model's `pi_model` (`/`, as an Agent's `runtime_model` stores it) is diff --git a/apps/computer/local-daemon/internal/localmodels/library.go b/apps/computer/local-daemon/internal/localmodels/library.go index 58aee26a9..f2a1cd05b 100644 --- a/apps/computer/local-daemon/internal/localmodels/library.go +++ b/apps/computer/local-daemon/internal/localmodels/library.go @@ -11,6 +11,7 @@ import ( "log/slog" "os" "path/filepath" + "slices" "sort" "strings" "sync" @@ -92,8 +93,12 @@ type Library struct { current *wire.LocalModelsSnapshot // loaded identifies the loaded models of the last status read; nil // before the first one. - loaded *string - jobs map[string]*job + loaded *string + jobs map[string]*job + // causes holds, by model, the cause the last job's error line gave. The + // tool's status keeps only the code, so each read puts the cause back on + // a row that still fails with that code. + causes map[string]*wire.LocalModelError lastProgress time.Time progressTimer *time.Timer // progressTimerID tells a timer callback that already fired whether it @@ -113,7 +118,7 @@ func New(options Options) *Library { tool: options.Tool, environment: options.Environment, jobDirectory: options.JobDirectory, publish: options.Publish, runtimeChanged: options.RuntimeChanged, progressInterval: options.ProgressInterval, statusTimeout: options.StatusTimeout, actionTimeout: options.ActionTimeout, - now: time.Now, ctx: ctx, stop: stop, jobs: make(map[string]*job), + now: time.Now, ctx: ctx, stop: stop, jobs: make(map[string]*job), causes: make(map[string]*wire.LocalModelError), } if library.progressInterval <= 0 { library.progressInterval = defaultProgressInterval @@ -190,9 +195,25 @@ func (l *Library) read(ctx context.Context) wire.LocalModelsSnapshot { slog.Warn("local_models.status_invalid", "error", err) return unavailable(CodeToolFailed, "localmodels reported a library status outside its contract", l.now()) } + l.restoreCauses(&snapshot) return snapshot } +// restoreCauses puts each kept cause back on its failed row, and forgets one +// whose row no longer fails with the code it came with. +func (l *Library) restoreCauses(snapshot *wire.LocalModelsSnapshot) { + l.mu.Lock() + defer l.mu.Unlock() + for id, cause := range l.causes { + index := slices.IndexFunc(snapshot.Models, func(model wire.LocalModel) bool { return model.ID == id }) + if index < 0 || snapshot.Models[index].Error == nil || snapshot.Models[index].Error.Code != cause.Code { + delete(l.causes, id) + continue + } + snapshot.Models[index].Error.Cause, snapshot.Models[index].Error.Path = cause.Cause, cause.Path + } +} + // loadedKey names the loaded models; a change means Pi's model list changed. func loadedKey(snapshot wire.LocalModelsSnapshot) string { var loaded []string @@ -482,6 +503,7 @@ func (l *Library) superviseJob(action Action, events <-chan libraryEvent, ended if accepted { l.mu.Lock() l.jobs[action.Model] = &job{action: action} + delete(l.causes, action.Model) l.mu.Unlock() } } @@ -532,6 +554,11 @@ func (l *Library) superviseJob(action Action, events <-chan libraryEvent, ended } l.mu.Lock() delete(l.jobs, action.Model) + if final != nil && final.Event == "error" { + if cause := final.cause(); cause != nil { + l.causes[action.Model] = cause + } + } l.mu.Unlock() l.Refresh(l.ctx) if action.Name == ActionLoad { diff --git a/apps/computer/local-daemon/internal/localmodels/library_test.go b/apps/computer/local-daemon/internal/localmodels/library_test.go index 8b9ca26ea..c21166964 100644 --- a/apps/computer/local-daemon/internal/localmodels/library_test.go +++ b/apps/computer/local-daemon/internal/localmodels/library_test.go @@ -622,3 +622,47 @@ func TestRefreshMapsRichModelCardMetadataAndKeepsItAcrossProgress(t *testing.T) t.Fatalf("progress dropped model card fields: %+v", after) } } + +// localmodels names why a load could not register with its gateway only on +// the job's error line; the snapshot's failed row carries it until another +// job for that model ends. +func TestAFailedLoadKeepsTheGatewayCauseOnItsRow(t *testing.T) { + fake := newFakeTool(t) + fake.write("status.json", status(model(testModel, "idle"))) + failed := model(testModel, "failed") + failed["error"] = map[string]any{"code": "GATEWAY_REGISTRATION_FAILED", "detail": "gateway-home is not private"} + encodedFailed, _ := json.Marshal(status(failed)) + const home = `C:\Users\ana\AppData\Local\localmodels\tools\gateway-home` + causeLine := errorLine(testModel, "GATEWAY_REGISTRATION_FAILED", `,"cause":"GATEWAY_HOME_NOT_PRIVATE","path":"C:\\Users\\ana\\AppData\\Local\\localmodels\\tools\\gateway-home"`) + fake.script("load", fakeScript{ + Lines: []fakeLine{{Line: progressLine(testModel, "load", 0, 2)}, {Line: causeLine, DelayMS: 20}}, + Exit: 1, StatusAfter: encodedFailed, + }) + record := &recorder{} + library := newLibrary(t, fake, record, 10*time.Millisecond) + library.Refresh(context.Background()) + + if refusal, _ := library.Act(context.Background(), Action{Name: ActionLoad, Model: testModel}, soon()); refusal != nil { + t.Fatalf("load refused: %+v", refusal) + } + waitFor(t, "the failed row with its cause", func() bool { + model := modelState(record.last(), testModel) + return model.State == "failed" && model.Error != nil && model.Error.Cause == "GATEWAY_HOME_NOT_PRIVATE" && model.Error.Path == home + }) + if again := modelState(library.Refresh(context.Background()), testModel); again.Error == nil || again.Error.Cause != "GATEWAY_HOME_NOT_PRIVATE" { + t.Fatalf("a later read dropped the cause: %+v", again.Error) + } + + // A retry that fails for another reason carries no stale cause. + fake.script("load", fakeScript{ + Lines: []fakeLine{{Line: progressLine(testModel, "load", 0, 2)}, {Line: errorLine(testModel, "GATEWAY_REGISTRATION_FAILED", ""), DelayMS: 20}}, + Exit: 1, StatusAfter: encodedFailed, + }) + if refusal, _ := library.Act(context.Background(), Action{Name: ActionLoad, Model: testModel}, soon()); refusal != nil { + t.Fatalf("retry refused: %+v", refusal) + } + waitFor(t, "the cause to clear", func() bool { + model := modelState(library.Refresh(context.Background()), testModel) + return model.Error != nil && model.Error.Cause == "" && model.Error.Path == "" + }) +} diff --git a/apps/computer/local-daemon/internal/localmodels/status.go b/apps/computer/local-daemon/internal/localmodels/status.go index be91b0f0b..1c55c3f3f 100644 --- a/apps/computer/local-daemon/internal/localmodels/status.go +++ b/apps/computer/local-daemon/internal/localmodels/status.go @@ -246,6 +246,8 @@ type libraryEvent struct { NeedBytes *float64 `json:"need_bytes"` FreeBytes *float64 `json:"free_bytes"` HaveBytes *float64 `json:"have_bytes"` + Cause string `json:"cause"` + Path string `json:"path"` } func parseEvent(line []byte) (libraryEvent, bool) { @@ -306,6 +308,19 @@ func bytesValue(value float64) uint64 { return uint64(value) } +// errorCauses is the tool's closed set of error causes; a GATEWAY_REGISTRATION_FAILED +// line carries one with the path it names. +var errorCauses = []string{"GATEWAY_HOME_NOT_PRIVATE"} + +// cause is the error line's cause as the wire carries it on a model's error, +// or nil when the line names none the contract knows. +func (e libraryEvent) cause() *wire.LocalModelError { + if !slices.Contains(errorCodes, e.Code) || !slices.Contains(errorCauses, e.Cause) || e.Path == "" { + return nil + } + return &wire.LocalModelError{Code: e.Code, Cause: e.Cause, Path: clip(e.Path, 4096)} +} + // clip bounds display text to the schema's length in characters. func clip(text string, limit int) string { if utf8.RuneCountInString(text) <= limit { diff --git a/apps/node-services/src/agent/AGENTS.md b/apps/node-services/src/agent/AGENTS.md index a417c027b..fc1cc7435 100644 --- a/apps/node-services/src/agent/AGENTS.md +++ b/apps/node-services/src/agent/AGENTS.md @@ -66,6 +66,12 @@ take precedence. cancellation, and the only Runtime execution path. Do not add a second scheduler, execution store, or Runtime executor beside it, and do not restore TeamHub Run admission. +- A Room Agent speaks only through TeamHub message writes, which the Computer + classifies as `message` activities (`reply-delivery.ts`). A Room Run whose + every write failed finishes failed with `reply_undelivered`. One that never + tried to write while a Human's Message that mentioned the Agent (a direct + chat always does) waits finishes failed with `reply_not_sent`. Its final + text is private scratch and is never posted for it. - Ordinary Room/Meta execution reads effective Agent configuration before a new Local Run. Skill saves do not activate idle Contexts. If versions changed, reuse graceful activation to resume the same native history; running/steered diff --git a/apps/node-services/src/agent/executor/provider.ts b/apps/node-services/src/agent/executor/provider.ts index dda556494..34e2d51c0 100644 --- a/apps/node-services/src/agent/executor/provider.ts +++ b/apps/node-services/src/agent/executor/provider.ts @@ -459,6 +459,7 @@ export interface RuntimeExecutionFailure { | "execution_failed" | "execution_outcome_unknown" | "reply_undelivered" + | "reply_not_sent" | "interrupted" | "computer_unavailable" | "cleanup_unconfirmed" diff --git a/apps/node-services/src/agent/executor/reply-delivery.ts b/apps/node-services/src/agent/executor/reply-delivery.ts index f93d8772e..8257ab5fc 100644 --- a/apps/node-services/src/agent/executor/reply-delivery.ts +++ b/apps/node-services/src/agent/executor/reply-delivery.ts @@ -1,19 +1,30 @@ +import { isRecord } from "@linger/service-kit"; import type { RunEvent } from "./provider.js"; +import type { Message } from "./types.js"; /** * The Run's TeamHub message calls, as the Computer classifies them: a * `message` activity is a message write (`teamhub message send` and its * siblings), `message_read` any other `teamhub message` call, and a command - * that exits non-zero finishes as failed. + * that exits non-zero finishes as failed. An emoji Reaction is a message + * write too. */ export class ReplyDelivery { readonly #started = new Map(); + #awaitingHuman = false; + #attemptedWrites = 0; #failedWrites = 0; #deliveredWrites = 0; #failedReads = 0; + /** Records the inputs the Run took up, at its start or as steers. */ + observeInputs(messages: readonly Message[]): void { + if (messages.some(awaitsReply)) this.#awaitingHuman = true; + } + observe(event: RunEvent): void { if (event.type === "activity.started") { + if (event.kind === "message") this.#attemptedWrites += 1; if (event.kind === "message" || event.kind === "message_read") this.#started.set(event.activityId, event.kind); return; @@ -39,6 +50,15 @@ export class ReplyDelivery { return this.#failedWrites > 0 && this.#deliveredWrites === 0; } + /** + * A Human who mentioned the Agent is waiting and the Agent never tried to + * post. Its Runtime ended the turn in text nobody sees; small models do + * this when they answer without calling the message command. + */ + get replyNotSent(): boolean { + return this.#awaitingHuman && this.#attemptedWrites === 0; + } + get hasFailures(): boolean { return this.#failedWrites > 0 || this.#failedReads > 0; } @@ -55,3 +75,23 @@ export class ReplyDelivery { }; } } + +/** + * Whether TeamHub queued this input for a Human's Message that mentioned this + * Agent. A direct chat mentions its Agent too. Room talk the Agent only reads + * along with, a Routine wake, a Task callback and another Agent's Message may + * rightly go unanswered. + */ +function awaitsReply(message: Message): boolean { + const notification = (message as unknown as Record) + .acceptedNotification; + if (!isRecord(notification) || !Array.isArray(notification.messages)) + return false; + return notification.messages.some( + (queued) => + isRecord(queued) && + queued.mentioned === true && + queued.authorType === "user" && + queued.messageKind === "conversation", + ); +} diff --git a/apps/node-services/src/agent/executor/run-loop.ts b/apps/node-services/src/agent/executor/run-loop.ts index cd9284ca2..b66d1d2e7 100644 --- a/apps/node-services/src/agent/executor/run-loop.ts +++ b/apps/node-services/src/agent/executor/run-loop.ts @@ -239,6 +239,7 @@ interface ActiveExecution { readonly runId: string; readonly sourceInboxIds: Set; readonly steerOperations: Set>; + readonly replyDelivery: ReplyDelivery; acceptingSteers: boolean; } @@ -1005,6 +1006,7 @@ export class RunLoop { ); } const replyDelivery = new ReplyDelivery(); + replyDelivery.observeInputs(execution.messages); let resumeStartRetries = 0; for (;;) { controller.signal.throwIfAborted(); @@ -1052,7 +1054,12 @@ export class RunLoop { execution.run = run; const providerReadyAt = performance.now(); this.#logProviderReady(execution, run, providerStartAt, providerReadyAt); - const active = await this.#activateExecution(execution, run, input); + const active = await this.#activateExecution( + execution, + run, + input, + replyDelivery, + ); execution.runtimeStatus ??= await this.#openRuntimeStatus( runId, @@ -1291,6 +1298,7 @@ export class RunLoop { execution: LocalRunExecution, run: AgentRun, input: AgentInput, + replyDelivery: ReplyDelivery, ): Promise { const { runId, controller } = execution; if ((await this.#state.getLocalRun(runId))?.cancellationRequested) { @@ -1322,6 +1330,7 @@ export class RunLoop { this.#activeExecution?.sourceInboxIds ?? new Set(execution.provenance.sourceInboxIds), steerOperations: new Set(), + replyDelivery, }; this.#activeExecution = active; execution.intent.resolveProviderReady(active); @@ -1717,19 +1726,19 @@ export class RunLoop { } /** - * A Room Agent speaks only through TeamHub message writes. When it tried to - * post and none landed, the Room has nothing to show, so a finished Provider - * turn is not a succeeded Run. Task Runs report through their final - * response and keep it. + * A Room Agent speaks only through TeamHub message writes, so a finished + * Provider turn is not a succeeded Run when the Room has nothing to show: + * the Agent tried to post and none landed, or a Human who mentioned it is + * waiting and it never tried. Its final text is private scratch and is not + * posted for it. Task Runs report through their final response and keep it. */ #completedTerminal( runId: string, finalResponse: string, replyDelivery: ReplyDelivery, ): LocalRunTerminal { - const undelivered = - this.#executionContextRef?.kind === "meta" && - replyDelivery.replyUndelivered; + const roomRun = this.#executionContextRef?.kind === "meta"; + const undelivered = roomRun && replyDelivery.replyUndelivered; if (replyDelivery.hasFailures) { this.#logger.log("warn", "local_run.teamhub_messages_failed", { runId, @@ -1738,14 +1747,26 @@ export class RunLoop { finalResponseLength: finalResponse.length, }); } - if (!undelivered) { - return { type: "succeeded", finalResponse }; + if (undelivered) { + return { + type: "failed", + error: "Agent reply was not delivered to the Room", + failure: runFailure("reply_undelivered", this.#runtimeType), + }; } - return { - type: "failed", - error: "Agent reply was not delivered to the Room", - failure: runFailure("reply_undelivered", this.#runtimeType), - }; + if (roomRun && replyDelivery.replyNotSent) { + this.#logger.log("warn", "local_run.reply_not_sent", { + runId, + ...replyDelivery.counts(), + finalResponseLength: finalResponse.length, + }); + return { + type: "failed", + error: "Agent ended its turn without sending a reply to the Room", + failure: runFailure("reply_not_sent", this.#runtimeType), + }; + } + return { type: "succeeded", finalResponse }; } #reportTerminal(runId: string, terminal: LocalTurnTerminal): void { @@ -1839,6 +1860,7 @@ export class RunLoop { target.sourceInboxIds.add(inboxId); } target.inputs.push(input); + target.replyDelivery.observeInputs(messages); this.#reportActiveRunContext({ runId: target.runId, sourceInboxIds: Object.freeze([...target.sourceInboxIds]), diff --git a/apps/node-services/tests/agent/executor/run-loop.test.ts b/apps/node-services/tests/agent/executor/run-loop.test.ts index 38efd7482..506f05b1b 100644 --- a/apps/node-services/tests/agent/executor/run-loop.test.ts +++ b/apps/node-services/tests/agent/executor/run-loop.test.ts @@ -332,6 +332,9 @@ describe("RunLoop", () => { const finishRun = async ( events: readonly RunEvent[], executionContextRef?: ExecutionContextRef, + input: Message = message("introduce yourself"), + finalResponse = "I could not deliver the reply: TeamHub returned 404.", + steered?: Message, ) => { const harness = createHarness( undefined, @@ -342,11 +345,19 @@ describe("RunLoop", () => { ); const run = new FakeRun(events); harness.provider.runs.push(run); - const runId = enqueue(harness.state, message("introduce yourself")); + const runId = enqueue(harness.state, input); try { harness.execution.start(); await vi.waitFor(() => expect(run.waitCalls).toBe(1)); - run.complete("I could not deliver the reply: TeamHub returned 404."); + if (steered) { + const steer = selectSteer(harness.state, steered); + await harness.execution.steer( + steer.groupId, + steer.messages, + new AbortController().signal, + ); + } + run.complete(finalResponse); await vi.waitFor(() => expect(harness.state.getLocalRun(runId)?.status).not.toBe("running"), ); @@ -424,6 +435,125 @@ describe("RunLoop", () => { ); }); + // TeamHub freezes each Inbox Message's sender, kind and whether it + // mentioned this Agent into the queued input. + const inboxInput = ( + inputId: string, + queued: { + readonly authorType: "agent" | "user"; + readonly messageKind: string; + readonly mentioned: boolean; + }, + ): Message => + ({ + ...message(inputId, "room:room-1"), + acceptedNotification: { + inboxId: "room:room-1", + after: "0", + through: "1", + targeted: queued.mentioned, + messages: [ + { + id: `${inputId}-message`, + body: "how are you?", + author: "Leo", + authorActorId: "actor-leo", + ...queued, + }, + ], + }, + }) as Message; + const humanMention = (inputId: string) => + inboxInput(inputId, { + authorType: "user", + messageKind: "conversation", + mentioned: true, + }); + + it("fails a Room Run that posted nothing while the Human who mentioned the Agent waits", async () => { + const { log, run } = await finishRun( + failedRead, + undefined, + humanMention("mention"), + "Doing well, you?", + ); + + expect(run).toMatchObject({ + status: "failed", + terminal: { + type: "failed", + failure: { code: "reply_not_sent", runtime_type: "pi" }, + }, + }); + expect(JSON.stringify(run?.terminal)).not.toContain("Doing well"); + expect(log).toHaveBeenCalledWith( + "warn", + "local_run.reply_not_sent", + expect.objectContaining({ + runId: run?.runId, + deliveredMessageWrites: 0, + finalResponseLength: "Doing well, you?".length, + }), + ); + }); + + it("fails a Room Run that posted nothing after a Human mention was steered into it", async () => { + const { run } = await finishRun( + [], + undefined, + inboxInput("room-talk", { + authorType: "user", + messageKind: "conversation", + mentioned: false, + }), + "", + humanMention("steered-mention"), + ); + + expect(run?.terminal).toMatchObject({ + type: "failed", + failure: { code: "reply_not_sent" }, + }); + }); + + it("keeps a Room Run succeeded when it answered a Human mention with a message", async () => { + const { run } = await finishRun( + messageWrite("send-1", "succeeded"), + undefined, + humanMention("mention"), + "", + ); + + expect(run?.terminal).toMatchObject({ type: "succeeded" }); + }); + + it.each([ + [ + "Room talk that did not mention the Agent", + { authorType: "user", messageKind: "conversation", mentioned: false }, + ], + [ + "a routine wake that mentions the Agent", + { authorType: "user", messageKind: "agent_runtime", mentioned: true }, + ], + [ + "another Agent's mention", + { authorType: "agent", messageKind: "conversation", mentioned: true }, + ], + ] as const)( + "keeps a Room Run that stayed silent on %s succeeded", + async (_label, queued) => { + const { run } = await finishRun( + [], + undefined, + inboxInput("wake", queued), + "Nothing to add.", + ); + + expect(run?.terminal).toMatchObject({ type: "succeeded" }); + }, + ); + it("leaves a Task Run, which reports through its final response, succeeded", async () => { const { run } = await finishRun(messageWrite("send-1", "failed"), { kind: "alter_ego", diff --git a/apps/teamhub/internal/agentruntimestate/runtime_failure.go b/apps/teamhub/internal/agentruntimestate/runtime_failure.go index fc7fd892e..bca77f325 100644 --- a/apps/teamhub/internal/agentruntimestate/runtime_failure.go +++ b/apps/teamhub/internal/agentruntimestate/runtime_failure.go @@ -32,7 +32,7 @@ func terminalRuntimeFailure(raw json.RawMessage) (*PublicRuntimeFailure, error) switch failure.Code { case "session_not_found", "protocol_incompatible", "authentication_required", "network_error", "rate_limited", "model_unavailable", "model_not_offered", "context_too_long", "model_service_error", "timeout", "execution_failed", - "execution_outcome_unknown", "reply_undelivered", "interrupted", "computer_unavailable", + "execution_outcome_unknown", "reply_undelivered", "reply_not_sent", "interrupted", "computer_unavailable", "cleanup_unconfirmed", "response_too_large", "unclassified": default: return nil, ErrInvalid diff --git a/apps/teamhub/internal/agentruntimestate/runtime_failure_test.go b/apps/teamhub/internal/agentruntimestate/runtime_failure_test.go index cb73f4de5..ff01465d2 100644 --- a/apps/teamhub/internal/agentruntimestate/runtime_failure_test.go +++ b/apps/teamhub/internal/agentruntimestate/runtime_failure_test.go @@ -13,6 +13,7 @@ func TestTerminalRuntimeFailure(t *testing.T) { {"legacy", `{"type":"failed","error":"private error"}`, true}, {"unknown execution outcome", `{"type":"failed","failure":{"code":"execution_outcome_unknown","runtime_type":"claude"}}`, true}, {"reply never reached the Room", `{"type":"failed","error":"Agent reply was not delivered to the Room","failure":{"code":"reply_undelivered","runtime_type":"pi"}}`, true}, + {"no reply sent to a waiting Human", `{"type":"failed","error":"Agent ended its turn without sending a reply to the Room","failure":{"code":"reply_not_sent","runtime_type":"pi"}}`, true}, {"model refused for the account", `{"type":"failed","failure":{"code":"model_unavailable","runtime_type":"codex","runtime_version":"0.153.4"}}`, true}, {"Computer does not offer the model", `{"type":"failed","error":"Local Computer model is unavailable","failure":{"code":"model_not_offered","runtime_type":"codex"}}`, true}, {"canceled cannot claim unknown failure", `{"type":"canceled","failure":{"code":"execution_outcome_unknown","runtime_type":"codex"}}`, false}, diff --git a/apps/teamhub/internal/app/handlers_local_models.go b/apps/teamhub/internal/app/handlers_local_models.go index 7ed76098a..7716e2954 100644 --- a/apps/teamhub/internal/app/handlers_local_models.go +++ b/apps/teamhub/internal/app/handlers_local_models.go @@ -147,6 +147,10 @@ func localModelsView(record agentruntimestate.LocalModelsRecord, viewerID string } } } + // A cause's path is a folder on the owner's machine; only they can act on it. + if model.Error != nil && !view.ViewerIsOwner { + model.Error.Path = nil + } view.Models = append(view.Models, httpapi.LocalModelView{Model: model, UsedBy: users}) } return view, nil @@ -341,6 +345,9 @@ func validLocalModelsSnapshot(snapshot teamhubinternal.LocalModelsSnapshot) bool if model.PromptTokensPerSecond != nil && *model.PromptTokensPerSecond < 0 { return false } + if model.Error != nil && model.Error.Cause != nil && !model.Error.Cause.Valid() { + return false + } seen[model.Id] = true } return true diff --git a/apps/teamhub/internal/app/handlers_local_models_test.go b/apps/teamhub/internal/app/handlers_local_models_test.go index 690b750be..65e11da9b 100644 --- a/apps/teamhub/internal/app/handlers_local_models_test.go +++ b/apps/teamhub/internal/app/handlers_local_models_test.go @@ -3,6 +3,7 @@ package app import ( "encoding/json" "slices" + "strings" "testing" "time" @@ -97,6 +98,29 @@ func TestLocalModelsViewMatchesAgentsToModelsOnTheComputer(t *testing.T) { } } +// The folder a gateway cause names is a path on the owner's machine: only +// the owner, who can rename it, reads it. +func TestLocalModelsViewShowsTheCausePathOnlyToTheOwner(t *testing.T) { + snapshot := strings.Replace(storedLocalModelsSnapshotJSON, `"state":"idle"`, + `"state":"failed","error":{"code":"GATEWAY_REGISTRATION_FAILED","cause":"GATEWAY_HOME_NOT_PRIVATE","path":"/home/ana/.local/share/localmodels/tools/gateway-home"}`, 1) + record := agentruntimestate.LocalModelsRecord{ + ComputerID: "computer_1", DisplayName: "Studio", Status: "offline", + Owner: agentruntimestate.LocalComputerOwner{TenantID: "tenant_1", OwnerActorID: "actor_owner"}, + Snapshot: json.RawMessage(snapshot), + } + for viewer, wantPath := range map[string]bool{"actor_owner": true, "actor_member": false} { + view, err := localModelsView(record, viewer, time.Now()) + if err != nil { + t.Fatal(err) + } + failed := view.Models[2].Model.Error + if failed == nil || failed.Cause == nil || *failed.Cause != httpapi.LocalModelErrorCauseGatewayHomeNotPrivate || + (failed.Path != nil) != wantPath { + t.Fatalf("%s: error=%+v", viewer, failed) + } + } +} + func TestLocalModelsViewWithoutSnapshotIsNotReported(t *testing.T) { view, err := localModelsView(agentruntimestate.LocalModelsRecord{ComputerID: "computer_1", DisplayName: "Studio", Status: "offline"}, "actor_owner", time.Now()) if err != nil || view.Available || view.Reason == nil || view.Reason.Code != httpapi.LocalModelsViewNotReported || @@ -179,6 +203,11 @@ func TestValidLocalModelsSnapshot(t *testing.T) { u := "http://huggingface.co/Qwen/Qwen3-4B" s.Models[0].SourceUrl = &u }, + "unknown error cause": func(s *teamhubinternal.LocalModelsSnapshot) { + c := teamhubinternal.LocalModelErrorCause("DISK_LOCKED") + s.Models[0].State = teamhubinternal.LocalModelStateFailed + s.Models[0].Error = &teamhubinternal.LocalModelError{Code: "GATEWAY_REGISTRATION_FAILED", Cause: &c} + }, "negative prompt_tokens_per_second": func(s *teamhubinternal.LocalModelsSnapshot) { p := float32(-1) s.Models[0].PromptTokensPerSecond = &p diff --git a/apps/teamhub/internal/app/handlers_message_attachment.go b/apps/teamhub/internal/app/handlers_message_attachment.go index 60c30ce2e..41d6744b6 100644 --- a/apps/teamhub/internal/app/handlers_message_attachment.go +++ b/apps/teamhub/internal/app/handlers_message_attachment.go @@ -11,6 +11,7 @@ import ( "github.com/simplexai-labs/linger/apps/teamhub/internal/collaboration" "github.com/simplexai-labs/linger/apps/teamhub/internal/idempotency" "github.com/simplexai-labs/linger/apps/teamhub/internal/secretbox" + httpapi "github.com/simplexai-labs/linger/contracts-go/teamhubpublic" ) func (a *App) uploadMessageAttachment(c *gin.Context) { @@ -21,7 +22,9 @@ func (a *App) uploadMessageAttachment(c *gin.Context) { upload, err := a.parseMessageAttachmentUpload(c) if err != nil { if errors.Is(err, artifactstore.ErrTooLarge) || isMaxBytesError(err) { - a.writeError(c, http.StatusRequestEntityTooLarge, "PAYLOAD_TOO_LARGE", "message attachment exceeds the configured limit") + code, limit := "too_large", a.cfg.ArtifactMaxBytes + a.writeErrorWithDetails(c, http.StatusRequestEntityTooLarge, "PAYLOAD_TOO_LARGE", "message attachment exceeds the configured limit", + []httpapi.ErrorDetail{{Field: "content", Code: &code, Reason: "exceeds the attachment size limit", LimitBytes: &limit}}) } else { a.writeError(c, http.StatusBadRequest, "INVALID_REQUEST", "message attachment upload is invalid") } diff --git a/apps/teamhub/internal/app/handlers_upload_too_large_test.go b/apps/teamhub/internal/app/handlers_upload_too_large_test.go index 630ba2460..094de7d36 100644 --- a/apps/teamhub/internal/app/handlers_upload_too_large_test.go +++ b/apps/teamhub/internal/app/handlers_upload_too_large_test.go @@ -2,6 +2,7 @@ package app import ( "bytes" + "encoding/json" "mime/multipart" "net/http" "net/http/httptest" @@ -11,6 +12,7 @@ import ( "github.com/gin-gonic/gin" "github.com/simplexai-labs/linger/apps/teamhub/internal/config" + httpapi "github.com/simplexai-labs/linger/contracts-go/teamhubpublic" ) // The multipart parser must surface *http.MaxBytesError so handlers map an @@ -56,3 +58,55 @@ func TestMultipartUploadsMapOversizedBodyToPayloadTooLarge(t *testing.T) { }) } } + +// A refused message attachment names the limit as a structured detail, so a +// client can tell the person how large a file may be. +func TestMessageAttachmentTooLargeNamesTheLimit(t *testing.T) { + t.Parallel() + const maxBytes = 16 + for name, size := range map[string]int{ + "file over the limit": maxBytes + 1, + "body over the limit": maxBytes + (1 << 20) + 1, + } { + t.Run(name, func(t *testing.T) { + var body bytes.Buffer + writer := multipart.NewWriter(&body) + if err := writer.WriteField("filename", "big.zip"); err != nil { + t.Fatal(err) + } + part, err := writer.CreateFormFile("content", "big.zip") + if err != nil { + t.Fatal(err) + } + if _, err := part.Write(bytes.Repeat([]byte("x"), size)); err != nil { + t.Fatal(err) + } + if err := writer.Close(); err != nil { + t.Fatal(err) + } + recorder := httptest.NewRecorder() + context, _ := gin.CreateTestContext(recorder) + context.Set("request_id", "request-attachment-too-large") + context.Request = httptest.NewRequest(http.MethodPost, "/upload", &body) + context.Request.Header.Set("Content-Type", writer.FormDataContentType()) + context.Request.Header.Set("Idempotency-Key", "attachment-too-large-key") + (&App{cfg: config.ForTest(func(c *config.Config) { + c.ArtifactMaxBytes = maxBytes + })}).uploadMessageAttachment(context) + + var response httpapi.ErrorResponse + if err := json.Unmarshal(recorder.Body.Bytes(), &response); err != nil { + t.Fatal(err) + } + if recorder.Code != http.StatusRequestEntityTooLarge || response.Error.Code != "PAYLOAD_TOO_LARGE" || + response.Error.Details == nil || len(*response.Error.Details) != 1 { + t.Fatalf("status=%d body=%s", recorder.Code, recorder.Body.String()) + } + detail := (*response.Error.Details)[0] + if detail.Field != "content" || detail.Code == nil || *detail.Code != "too_large" || + detail.LimitBytes == nil || *detail.LimitBytes != maxBytes { + t.Fatalf("detail = %+v", detail) + } + }) + } +} diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md index 2a43eafc3..e7ded5f5c 100644 --- a/apps/web/AGENTS.md +++ b/apps/web/AGENTS.md @@ -47,8 +47,13 @@ build:assets` to check the initial JS budget. its own Computer. Only the Computer's owner can act; actions return at once and progress arrives as `local-models` invalidation hints. From the click until a snapshot with another status or observation time, or a refusal, the - row shows a requested load or download as started and spins the button of - any other action, with the row's actions off. A Computer's + row shows a requested load or download as started, labels a cancel, unload + or remove under way (Cancelling, Unloading, Removing), and spins that + action's button, with the row's actions off; a download the Computer + accepted can be cancelled before its first progress. Make room lists what + else holds the pool (components, and other apps from `used_bytes` no holder + accounts for) when unloading models cannot free enough, and says a model + cannot fit only when it needs more than the pool's total. A Computer's detail on the Computers page links here and reads no model state itself. - `src/test`: unit-test support, including the in-process TeamHub test server. - `e2e`: Playwright product workflows; every spec runs on the real TeamHub and diff --git a/apps/web/src/features/local-models/local-model-details.tsx b/apps/web/src/features/local-models/local-model-details.tsx index 61f276f8f..e74b9d880 100644 --- a/apps/web/src/features/local-models/local-model-details.tsx +++ b/apps/web/src/features/local-models/local-model-details.tsx @@ -127,7 +127,7 @@ export function ModelFacts({ label={stopped ? "Last download" : "Last load"} > - {modelErrorCopy(model.error.code)} + {modelErrorCopy(model.error)} ) : null} diff --git a/apps/web/src/features/local-models/local-model-dialogs.tsx b/apps/web/src/features/local-models/local-model-dialogs.tsx index f8e36a51a..eee661e37 100644 --- a/apps/web/src/features/local-models/local-model-dialogs.tsx +++ b/apps/web/src/features/local-models/local-model-dialogs.tsx @@ -12,6 +12,7 @@ import { formatGigabytes, makeRoomSelection, makesRoom, + placeName, poolLabel, poolOf, poolOtherBytes, @@ -64,17 +65,29 @@ export function MakeRoomDialog({ const effectiveSelected = roomFreeNow ? [] : selected; const chosen = new Set(effectiveSelected); const enough = roomFreeNow || makesRoom(check, chosen); + const pool = poolLabel(view, check.pool); const otherBytes = poolOtherBytes(check.pool); const unifiedFitsHardware = check.pool.kind === "unified" && (view.computer.host?.ram_total_bytes ?? 0) >= check.needBytes; + // Whether unloading every model offered here frees enough; when not, what + // else holds the memory is the thing to show. + const reachable = + roomFreeNow || + makesRoom(check, new Set(check.loaded.map((item) => item.model.id))); + // Free memory never exceeds the pool's total, whatever else closes. + const tooBig = check.needBytes > check.pool.total_bytes; + const inUse = [ + ...(otherBytes ? [{ bytes: otherBytes, id: "", name: "Other apps" }] : []), + ...check.kept, + ]; const affected = check.loaded.flatMap((item) => chosen.has(item.model.id) ? item.used_by.map((user) => user.name) : [], ); return ( {onRecheck ? ( @@ -147,19 +160,44 @@ export function MakeRoomDialog({ ))} - ) : ( + ) : null} + {tooBig ? ( - Nothing else is loaded there. - {otherBytes > 0 || unifiedFitsHardware - ? `${otherBytes > 0 ? ` Other apps are using ${formatGigabytes(otherBytes)}.` : ""} Close video players, games, or other memory-heavy apps, then click Recheck memory so loading won't overload your computer.` - : " This model doesn't fit even when the memory is empty."} + {entry.model.name} needs more than all{" "} + {formatGigabytes(check.pool.total_bytes)} of {pool}, so it + can't load there. + ) : reachable ? null : ( + <> + {inUse.length ? ( +
    + {inUse.map((holder) => ( +
  • + + {holder.name} + + + {formatGigabytes(holder.bytes)} + +
  • + ))} +
+ ) : null} + + {otherBytes > 0 || unifiedFitsHardware + ? `${otherBytes > 0 ? `Other apps are using ${formatGigabytes(otherBytes)}. ` : ""}Close other apps that use ${placeName(view, check.pool.id)}, then ${onRecheck ? "click Recheck memory" : "try again"}.` + : "Unloading models here doesn't free enough. Choose a smaller model."} + + )} - {check.loaded.length > 0 && !enough && otherBytes > 0 ? ( + {reachable && !enough && otherBytes > 0 ? ( - Other apps are using {formatGigabytes(otherBytes)} on{" "} - {poolLabel(view, check.pool)}. Close unnecessary apps and click - Recheck memory to free the remaining room. + Other apps are using {formatGigabytes(otherBytes)} on {pool}. Close + unnecessary apps and click Recheck memory to free the remaining + room. ) : null} {affected.length ? ( diff --git a/apps/web/src/features/local-models/local-model-row.tsx b/apps/web/src/features/local-models/local-model-row.tsx index f3b7405e0..fca89c330 100644 --- a/apps/web/src/features/local-models/local-model-row.tsx +++ b/apps/web/src/features/local-models/local-model-row.tsx @@ -141,6 +141,17 @@ const statusTags: Record< unavailable: { label: "Can't download" }, }; +/** + * The label a row shows while an action that ends its current status is + * under way: until a snapshot moves the model on, the status alone would + * read as if nothing had happened. + */ +const endingLabels: Partial> = { + cancel: "Cancelling", + remove: "Removing", + unload: "Unloading", +}; + interface Handlers { onCancel: () => void; onDownload: () => void; @@ -320,19 +331,28 @@ export function ModelRow({ const panelId = useId(); const { model } = entry; // A requested load or download reads as started at once; the snapshot that - // follows says how it went. + // follows says how it went. A cancel can follow a download no snapshot + // shows yet. const status: ModelStatus = requested === "load" ? "loading" - : requested === "download" + : requested === "download" || + (requested === "cancel" && entry.status === "available") ? "downloading" : entry.status; const started = status !== entry.status; const stopped = status === "failed" && downloadStopped(model); const where = placeName(view, model.pool); - const tag = stopped - ? { ...statusTags.failed, label: "Download stopped" } - : statusTags[status]; + const ending = requested && endingLabels[requested]; + const tag = ending + ? { + dot: statusTags[status].dot, + label: stopped && requested === "cancel" ? "Discarding" : ending, + working: true, + } + : stopped + ? { ...statusTags.failed, label: "Download stopped" } + : statusTags[status]; const progress = downloadPercent(model); const download = formatGigabytes(model.download_bytes); const recommended = status === "available" && model.recommended; @@ -418,7 +438,7 @@ export function ModelRow({ {model.name} = { PLATFORM_UNSUPPORTED: "This model doesn't run on this computer.", }; -/** Why the last load or download of a model failed. */ -export function modelErrorCopy(code: Schemas["LocalModelErrorCode"]) { - return modelErrors[code]; +const modelErrorCauses: Record< + NonNullable, + (path: string | undefined) => string +> = { + GATEWAY_HOME_NOT_PRIVATE: (path) => + path + ? `It loaded, but Agents couldn't be given access to it: the folder ${path} belongs to another account. Quit Linger, rename that folder, then open Linger and load the model again.` + : "It loaded, but Agents couldn't be given access to it: a Linger folder on the computer belongs to another account.", +}; + +/** + * Why the last load or download of a model failed. A cause names the fix; + * its path reaches only the Computer's owner. + */ +export function modelErrorCopy(error: Schemas["LocalModelError"]) { + return error.cause + ? modelErrorCauses[error.cause](error.path) + : modelErrors[error.code]; } const notes: Record< diff --git a/apps/web/src/features/local-models/local-models-page.test.tsx b/apps/web/src/features/local-models/local-models-page.test.tsx index 00e30ea9e..2fe0e3dee 100644 --- a/apps/web/src/features/local-models/local-models-page.test.tsx +++ b/apps/web/src/features/local-models/local-models-page.test.tsx @@ -494,6 +494,70 @@ describe("LocalModelsPage", () => { answer(); }); + it("lets an accepted download be cancelled before its first progress", async () => { + const fixture = setup(); + await renderPage(fixture); + await findModels(); + + fireEvent.click( + screen.getByRole("button", { name: "Download GPT-OSS 20B" }), + ); + const cancel = await screen.findByRole("button", { + name: "Cancel GPT-OSS 20B", + }); + await waitFor(() => expect(cancel).toBeEnabled()); + expect(statusOf("GPT-OSS 20B")).toBe("Downloading"); + + const answer = holdActions(fixture, () => accepted("cancel")); + fireEvent.click(cancel); + await waitFor(() => expect(statusOf("GPT-OSS 20B")).toBe("Cancelling")); + expect( + screen.queryByRole("button", { name: "Download GPT-OSS 20B" }), + ).toBeNull(); + answer(); + }); + + it("shows a download as cancelling from the click until the Computer stops it", async () => { + const fixture = setup([ + withModel(labView(), "gpt-oss-20b:Q4_K_M", { + download: { done_bytes: 32, step: "download", total_bytes: 100 }, + state: "downloading", + }), + ]); + const answer = holdActions(fixture, () => accepted("cancel")); + await renderPage(fixture); + await findModels(); + + fireEvent.click(screen.getByRole("button", { name: "Cancel GPT-OSS 20B" })); + await waitFor(() => expect(statusOf("GPT-OSS 20B")).toBe("Cancelling")); + expect( + card("GPT-OSS 20B").querySelector(".town-shimmer-text"), + ).not.toBeNull(); + + // Progress keeps arriving while the tool stops the download. + publishSnapshot( + fixture, + withModel(labView(), "gpt-oss-20b:Q4_K_M", { + download: { done_bytes: 40, step: "download", total_bytes: 100 }, + state: "downloading", + }), + ); + await waitFor(() => + expect( + screen.getByRole("progressbar", { + name: "GPT-OSS 20B download progress", + }), + ).toHaveAttribute("aria-valuenow", "40"), + ); + expect(statusOf("GPT-OSS 20B")).toBe("Cancelling"); + + publishSnapshot(fixture, labView()); + answer(); + await waitFor(() => + expect(statusOf("GPT-OSS 20B")).toMatch(/^Not downloaded/), + ); + }); + it("discards a stopped download instead of removing it", async () => { const fixture = setup([ withModel(macView(), "llama3.3-70b:Q4_K_M", { @@ -526,6 +590,41 @@ describe("LocalModelsPage", () => { expect(screen.queryByRole("dialog")).not.toBeInTheDocument(); }); + it.each([ + [ + "/home/ana/.local/share/localmodels/tools/gateway-home", + "It loaded, but Agents couldn't be given access to it: the folder /home/ana/.local/share/localmodels/tools/gateway-home belongs to another account. Quit Linger, rename that folder, then open Linger and load the model again.", + ], + [ + undefined, + "It loaded, but Agents couldn't be given access to it: a Linger folder on the computer belongs to another account.", + ], + ])( + "explains a gateway folder another account owns (path %s)", + async (path, copy) => { + await renderPage( + setup([ + withModel(macView(), "llama3.3-70b:Q4_K_M", { + error: { + cause: "GATEWAY_HOME_NOT_PRIVATE", + code: "GATEWAY_REGISTRATION_FAILED", + detail: "raw gateway detail", + ...(path ? { path } : {}), + }, + }), + ]), + ); + await findModels(); + + fireEvent.click(screen.getByRole("button", { name: "Llama 3.3 70B" })); + const details = screen.getByRole("region", { + name: "Llama 3.3 70B details", + }); + expect(details).toHaveTextContent(copy); + expect(details).not.toHaveTextContent("raw gateway detail"); + }, + ); + it("retries a model that failed to load with a load and still offers Remove", async () => { const fixture = setup([ withModel(macView(), "llama3.3-70b:Q4_K_M", { @@ -654,9 +753,91 @@ describe("LocalModelsPage", () => { fireEvent.click( screen.getByRole("button", { name: "Retry Llama 3.3 70B" }), ); + const dialog = screen.getByRole("dialog", { name: "Make room to load" }); + expect(dialog).toHaveTextContent( + "Llama 3.3 70B needs more than all 40 GB of Unified memory, so it can't load there.", + ); + expect(within(dialog).getByRole("button", { name: "Load" })).toBeDisabled(); + }); + + it("names the apps holding the memory instead of calling the model too big", async () => { + const lab = labView(); + const qwen = localModel({ + id: "qwen3-14b:Q4_K_M", + memory_bytes: gb(8.9), + name: "Qwen3 14B", + pool: "gpu:0", + state: "idle", + }); + // A 16 GB card where Linger's embedding holds 1 GB and other apps 8 GB: + // the model fits the empty card but not what is free now. + const pool = gpuPool(0, 16, [ + { component: true, gb: 1, id: "embedding", name: "Qwen3 Embedding" }, + ]); + await renderPage( + setup([ + { + ...lab, + models: [modelView(qwen)], + pools: [{ ...pool, used_bytes: gb(9) }], + }, + ]), + ); + await findModels(); + + fireEvent.click(screen.getByRole("button", { name: "Load Qwen3 14B" })); + const dialog = screen.getByRole("dialog", { name: "Make room to load" }); + expect(dialog).toHaveTextContent( + "Qwen3 14B needs 8.9 GB on GPU 0 ยท RTX 4090; 7 GB is free.", + ); + expect(dialog).not.toHaveTextContent("empty"); + const inUse = within(dialog).getByRole("list", { + name: "Also using this memory", + }); + expect( + within(inUse) + .getAllByRole("listitem") + .map((item) => item.textContent), + ).toEqual(["Other apps8 GB", "Qwen3 Embedding1 GB"]); + expect(dialog).toHaveTextContent( + "Other apps are using 8 GB. Close other apps that use GPU 0, then click Recheck memory.", + ); + expect(within(dialog).getByRole("button", { name: "Load" })).toBeDisabled(); + }); + + it("lists other apps when unloading every model still isn't enough", async () => { + const lab = labView(); + const pool = gpuPool(0, 24, [ + { gb: 10, id: "qwen3-coder-30b:Q4_K_M", name: "Qwen3 Coder 30B" }, + ]); + await renderPage( + setup([ + withModel( + withModel( + { ...lab, pools: [{ ...pool, used_bytes: gb(22) }, lab.pools[1]!] }, + "qwen3-coder-30b:Q4_K_M", + { memory_bytes: gb(10) }, + ), + "gemma3-27b:Q4_K_M", + { pool: "gpu:0", memory_bytes: gb(13) }, + ), + ]), + ); + await findModels(); + + fireEvent.click(screen.getByRole("button", { name: "Load Gemma 3 27B" })); + const dialog = screen.getByRole("dialog", { name: "Make room to load" }); + expect( + within(dialog).getByRole("checkbox", { name: /Qwen3 Coder 30B/ }), + ).not.toBeChecked(); expect( - screen.getByRole("dialog", { name: "Make room to load" }), - ).toHaveTextContent("Nothing else is loaded there."); + within( + within(dialog).getByRole("list", { name: "Also using this memory" }), + ).getByRole("listitem"), + ).toHaveTextContent("Other apps12 GB"); + expect(dialog).toHaveTextContent( + "Other apps are using 12 GB. Close other apps that use GPU 0, then click Recheck memory.", + ); }); it("asks before unloading a model an Agent uses, and not otherwise", async () => { @@ -911,6 +1092,7 @@ describe("LocalModelsPage", () => { }); await waitFor(() => expect(unload).toHaveAttribute("aria-busy", "true")); expect(unload).toBeDisabled(); + expect(statusOf("Qwen3 Coder 30B")).toBe("Unloading"); answer(); publishSnapshot( diff --git a/apps/web/src/features/local-models/local-models-page.tsx b/apps/web/src/features/local-models/local-models-page.tsx index 5c95eb1f1..51831a50b 100644 --- a/apps/web/src/features/local-models/local-models-page.tsx +++ b/apps/web/src/features/local-models/local-models-page.tsx @@ -536,6 +536,12 @@ function Library({ for (const input of sending) { if (input) requests.set(input.modelId, input.action); } + // A download the Computer accepted is a job it can cancel before the + // first progress reaches a snapshot; every other request holds the row. + const busy = (modelId: string) => + requests.has(modelId) && + (requests.get(modelId) !== "download" || + sending.some((input) => input?.modelId === modelId)); const offline = view.computer.status === "offline"; const readOnly = !view.viewer_is_owner; // A dialog stays open across snapshots, so its confirm checks the model @@ -560,6 +566,7 @@ function Library({ (dialogPool ? { freeBytes: poolFreeBytes(dialogPool), + kept: [], loaded: [], needBytes: dialogEntry.model.memory_bytes, pool: dialogPool, @@ -671,9 +678,7 @@ function Library({ entry.model.id !== status.runtime_model; return ( { expect(check.loaded.map((entry) => entry.model.name)).toEqual([ "GPT-OSS 20B", ]); + // The loaded model is offered, so nothing else holds the pool. + expect(check.kept).toEqual([]); + expect(poolOtherBytes(check.pool)).toBe(0); }); it("preselects the fewest models, preferring ones no Agent uses", () => { @@ -289,6 +292,7 @@ describe("local models rules", () => { ...item, status: "loaded" as const, })), + kept: [], needBytes: gb(12), pool, }; diff --git a/apps/web/src/features/local-models/local-models-rules.ts b/apps/web/src/features/local-models/local-models-rules.ts index 8d10247bd..2fa2e9622 100644 --- a/apps/web/src/features/local-models/local-models-rules.ts +++ b/apps/web/src/features/local-models/local-models-rules.ts @@ -290,6 +290,11 @@ export interface LoadCheck { freeBytes: number; /** Loaded models in the same pool, the ones the user could unload. */ loaded: ModelEntry[]; + /** + * What else holds the pool that Make room cannot unload: components and + * models in another state, by holder. + */ + kept: LocalModelPool["holders"]; } /** Why a model cannot load now, or `null` when its pool reports room for it. */ @@ -299,14 +304,18 @@ export function loadCheck( ): LoadCheck | null { const pool = poolOf(view, model.pool); if (!pool || poolFreeBytes(pool) >= model.memory_bytes) return null; + const loaded = modelEntries(view).filter( + (entry) => + entry.status === "loaded" && + entry.model.pool === pool.id && + entry.model.id !== model.id, + ); return { freeBytes: poolFreeBytes(pool), - loaded: modelEntries(view).filter( - (entry) => - entry.status === "loaded" && - entry.model.pool === pool.id && - entry.model.id !== model.id, + kept: pool.holders.filter( + (holder) => !loaded.some((entry) => entry.model.id === holder.id), ), + loaded, needBytes: model.memory_bytes, pool, }; diff --git a/apps/web/src/features/rooms/chat/message-composer.test.tsx b/apps/web/src/features/rooms/chat/message-composer.test.tsx index bfc83ee40..804ba850f 100644 --- a/apps/web/src/features/rooms/chat/message-composer.test.tsx +++ b/apps/web/src/features/rooms/chat/message-composer.test.tsx @@ -17,6 +17,7 @@ import { formatSkillToken, } from "./message-composer-references"; import { TEAMHUB_MESSAGE_MAX_LENGTH } from "./use-composer-draft"; +import { TeamHubError } from "@/features/teamhub/teamhub-error"; import { createTeamHubMessageContent } from "@/features/teamhub/teamhub-message-content"; describe("MessageComposer", () => { @@ -461,6 +462,40 @@ describe("MessageComposer", () => { }); }); + it("names the file's size and the attachment limit when TeamHub refuses a large file", async () => { + const onStageAttachment = vi.fn().mockRejectedValue( + new TeamHubError({ + code: "PAYLOAD_TOO_LARGE", + details: [ + { + code: "too_large", + field: "content", + limit_bytes: 50 * 1024 * 1024, + reason: "exceeds the attachment size limit", + }, + ], + message: "message attachment exceeds the configured limit", + status: 413, + }), + ); + const file = new File([], "big.zip"); + Object.defineProperty(file, "size", { value: 60 * 1024 * 1024 }); + render( + , + ); + fireEvent.change(screen.getByLabelText("Choose message attachments"), { + target: { files: [file] }, + }); + + expect(await screen.findByRole("alert")).toHaveTextContent( + "big.zip: Attachments can be up to 50 MB, and this file is 60 MB.", + ); + }); + it("keeps the compact attachment remove control visible and cancels its staged upload", async () => { const onCancelAttachment = vi.fn().mockResolvedValue(undefined); const onStageAttachment = vi.fn().mockResolvedValue(undefined); diff --git a/apps/web/src/features/rooms/chat/use-composer-attachments.ts b/apps/web/src/features/rooms/chat/use-composer-attachments.ts index 6083ef8da..bacd8acbd 100644 --- a/apps/web/src/features/rooms/chat/use-composer-attachments.ts +++ b/apps/web/src/features/rooms/chat/use-composer-attachments.ts @@ -8,6 +8,8 @@ import { } from "react"; import { createTeamHubIdempotencyKey } from "@/features/teamhub/teamhub-client"; +import { TeamHubError } from "@/features/teamhub/teamhub-error"; +import { formatBytes } from "@/lib/format-bytes"; import { type ComposerAttachment, composerAttachmentStore, @@ -174,8 +176,7 @@ export function useComposerAttachments({ candidate.clientId === attachment.clientId ? { ...candidate, - error: - error instanceof Error ? error.message : "Upload failed.", + error: uploadFailureCopy(error, attachment.file), status: "failed", } : candidate, @@ -260,6 +261,18 @@ export function filesFromClipboard(clipboardData: DataTransfer): File[] { }); } +/** Why one upload failed; TeamHub's limit refusal names both sizes. */ +function uploadFailureCopy(error: unknown, file: File) { + if (error instanceof TeamHubError && error.code === "PAYLOAD_TOO_LARGE") { + const limit = error.details?.find( + (detail) => detail.code === "too_large", + )?.limit_bytes; + if (limit !== undefined) + return `Attachments can be up to ${formatBytes(limit)}, and this file is ${formatBytes(file.size)}.`; + } + return error instanceof Error ? error.message : "Upload failed."; +} + function validateMessageAttachments(files: File[]) { if (files.length > maximumAttachmentCount) { return { diff --git a/apps/web/src/features/rooms/runtime-status/runtime-failure-message.test.ts b/apps/web/src/features/rooms/runtime-status/runtime-failure-message.test.ts index 9ff99766b..93672bfdc 100644 --- a/apps/web/src/features/rooms/runtime-status/runtime-failure-message.test.ts +++ b/apps/web/src/features/rooms/runtime-status/runtime-failure-message.test.ts @@ -49,6 +49,16 @@ describe("Runtime failure messages", () => { expect(message).toContain("TeamHub"); }); + it("says the Agent finished without sending its reply", () => { + const message = runtimeFailureMessage({ + code: "reply_not_sent", + runtime_type: "pi", + }); + expect(message).toContain("Pi:"); + expect(message).toContain("finished without sending its reply"); + expect(message).toContain("choose a stronger model"); + }); + it("names a failure the Agent Service observed without a Runtime prefix", () => { expect(runtimeFailureMessage({ code: "interrupted" })).toMatch( /^The Run was interrupted before it finished/, diff --git a/apps/web/src/features/rooms/runtime-status/runtime-failure-message.ts b/apps/web/src/features/rooms/runtime-status/runtime-failure-message.ts index e1c6aebf0..f5278db27 100644 --- a/apps/web/src/features/rooms/runtime-status/runtime-failure-message.ts +++ b/apps/web/src/features/rooms/runtime-status/runtime-failure-message.ts @@ -27,6 +27,8 @@ const messages: Record = { "A command was dispatched, but its result could not be confirmed. It was not automatically replayed. Check its effects before retrying.", reply_undelivered: "The Agent finished, but its reply did not reach the Room because every TeamHub message it tried to send failed. Check the Agent's connection to TeamHub, then ask again.", + reply_not_sent: + "The Agent finished without sending its reply to the Room. Its model may have answered without using the message command. Ask again, or choose a stronger model for the Agent.", interrupted: "The Run was interrupted before it finished, for example by a restart or by stopping the Agent on its Computer. Part of its work may have taken effect; check the result before asking again.", computer_unavailable: diff --git a/contracts/generated/go/nodeservicesinternal/openapi.gen.go b/contracts/generated/go/nodeservicesinternal/openapi.gen.go index 243886b5a..d49cea501 100644 --- a/contracts/generated/go/nodeservicesinternal/openapi.gen.go +++ b/contracts/generated/go/nodeservicesinternal/openapi.gen.go @@ -1814,9 +1814,12 @@ type Error struct { // ErrorDetail defines model for ErrorDetail. type ErrorDetail struct { // Code Optional stable classification for this individual validation issue. - Code *string `json:"code,omitempty"` - Field string `json:"field"` - Reason string `json:"reason"` + Code *string `json:"code,omitempty"` + Field string `json:"field"` + + // LimitBytes With code too_large, the largest size the field accepts, in bytes. + LimitBytes *int64 `json:"limit_bytes,omitempty"` + Reason string `json:"reason"` } // ErrorResponse defines model for ErrorResponse. diff --git a/contracts/generated/go/runnergateway/wire.gen.go b/contracts/generated/go/runnergateway/wire.gen.go index ab8144c35..d752713af 100644 --- a/contracts/generated/go/runnergateway/wire.gen.go +++ b/contracts/generated/go/runnergateway/wire.gen.go @@ -1315,6 +1315,8 @@ func (LocalModelEndpoint) RequiredFields() []string { return []string{"base_url" type LocalModelError struct { Code string `json:"code"` Detail string `json:"detail,omitempty"` + Cause string `json:"cause,omitempty"` + Path string `json:"path,omitempty"` } // FixedFields lists the keys whose value the schema fixes for a LocalModelError. diff --git a/contracts/generated/go/teamhubinternal/openapi.gen.go b/contracts/generated/go/teamhubinternal/openapi.gen.go index 297d3ea08..96239af25 100644 --- a/contracts/generated/go/teamhubinternal/openapi.gen.go +++ b/contracts/generated/go/teamhubinternal/openapi.gen.go @@ -338,6 +338,7 @@ const ( NetworkError AgentRuntimeExecutionFailureCode = "network_error" ProtocolIncompatible AgentRuntimeExecutionFailureCode = "protocol_incompatible" RateLimited AgentRuntimeExecutionFailureCode = "rate_limited" + ReplyNotSent AgentRuntimeExecutionFailureCode = "reply_not_sent" ReplyUndelivered AgentRuntimeExecutionFailureCode = "reply_undelivered" ResponseTooLarge AgentRuntimeExecutionFailureCode = "response_too_large" SessionNotFound AgentRuntimeExecutionFailureCode = "session_not_found" @@ -374,6 +375,8 @@ func (e AgentRuntimeExecutionFailureCode) Valid() bool { return true case RateLimited: return true + case ReplyNotSent: + return true case ReplyUndelivered: return true case ResponseTooLarge: @@ -836,6 +839,21 @@ func (e LocalModelDownloadProgressStep) Valid() bool { } } +// Defines values for LocalModelErrorCause. +const ( + LocalModelErrorCauseGatewayHomeNotPrivate LocalModelErrorCause = "GATEWAY_HOME_NOT_PRIVATE" +) + +// Valid indicates whether the value is a known member of the LocalModelErrorCause enum. +func (e LocalModelErrorCause) Valid() bool { + switch e { + case LocalModelErrorCauseGatewayHomeNotPrivate: + return true + default: + return false + } +} + // Defines values for LocalModelErrorCode. const ( CANCELLED LocalModelErrorCode = "CANCELLED" @@ -2405,7 +2423,7 @@ type AgentRuntimeDeletionSnapshot struct { TenantId Id `json:"tenant_id"` } -// AgentRuntimeExecutionFailure Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. +// AgentRuntimeExecutionFailure Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. reply_not_sent means a Room Run finished without trying to post anything while a Human who mentioned the Agent waited for its reply; the Runtime ended the turn in text nobody sees, which is not posted for it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. type AgentRuntimeExecutionFailure struct { Code AgentRuntimeExecutionFailureCode `json:"code"` RuntimeType *LocalRuntimeType `json:"runtime_type,omitempty"` @@ -3065,9 +3083,12 @@ type Error struct { // ErrorDetail defines model for ErrorDetail. type ErrorDetail struct { // Code Optional stable classification for this individual validation issue. - Code *string `json:"code,omitempty"` - Field string `json:"field"` - Reason string `json:"reason"` + Code *string `json:"code,omitempty"` + Field string `json:"field"` + + // LimitBytes With code too_large, the largest size the field accepts, in bytes. + LimitBytes *int64 `json:"limit_bytes,omitempty"` + Reason string `json:"reason"` } // ErrorResponse defines model for ErrorResponse. @@ -3091,7 +3112,7 @@ type FinishAgentLocalRunRequestTerminalType string // FinishAgentLocalRunRequest_Terminal defines model for FinishAgentLocalRunRequest.Terminal. type FinishAgentLocalRunRequest_Terminal struct { - // Failure Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. + // Failure Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. reply_not_sent means a Room Run finished without trying to post anything while a Human who mentioned the Agent waited for its reply; the Runtime ended the turn in text nobody sees, which is not posted for it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. Failure *AgentRuntimeExecutionFailure `json:"failure,omitempty"` Type FinishAgentLocalRunRequestTerminalType `json:"type"` AdditionalProperties map[string]interface{} `json:"-"` @@ -3225,13 +3246,22 @@ type LocalModelEndpoint struct { // LocalModelError defines model for LocalModelError. type LocalModelError struct { + // Cause Why a GATEWAY_REGISTRATION_FAILED happened, when the Computer supervised the failed job. GATEWAY_HOME_NOT_PRIVATE: the local gateway's private folder at path has another owner; closing Linger and renaming that folder lets the model load. + Cause *LocalModelErrorCause `json:"cause,omitempty"` + // Code Closed localmodels library error set. It is extended only together with the localmodels library contract. Code LocalModelErrorCode `json:"code"` // Detail Diagnostic text for display; never matched on. Detail *string `json:"detail,omitempty"` + + // Path The folder the cause names, on the Computer. The public view carries it only for the Computer's owner. + Path *string `json:"path,omitempty"` } +// LocalModelErrorCause Why a GATEWAY_REGISTRATION_FAILED happened, when the Computer supervised the failed job. GATEWAY_HOME_NOT_PRIVATE: the local gateway's private folder at path has another owner; closing Linger and renaming that folder lets the model load. +type LocalModelErrorCause string + // LocalModelErrorCode Closed localmodels library error set. It is extended only together with the localmodels library contract. type LocalModelErrorCode string diff --git a/contracts/generated/go/teamhubpublic/openapi.gen.go b/contracts/generated/go/teamhubpublic/openapi.gen.go index 61c5dca7d..101a6d8dd 100644 --- a/contracts/generated/go/teamhubpublic/openapi.gen.go +++ b/contracts/generated/go/teamhubpublic/openapi.gen.go @@ -239,6 +239,7 @@ const ( AgentRuntimeExecutionFailureCodeNetworkError AgentRuntimeExecutionFailureCode = "network_error" AgentRuntimeExecutionFailureCodeProtocolIncompatible AgentRuntimeExecutionFailureCode = "protocol_incompatible" AgentRuntimeExecutionFailureCodeRateLimited AgentRuntimeExecutionFailureCode = "rate_limited" + AgentRuntimeExecutionFailureCodeReplyNotSent AgentRuntimeExecutionFailureCode = "reply_not_sent" AgentRuntimeExecutionFailureCodeReplyUndelivered AgentRuntimeExecutionFailureCode = "reply_undelivered" AgentRuntimeExecutionFailureCodeResponseTooLarge AgentRuntimeExecutionFailureCode = "response_too_large" AgentRuntimeExecutionFailureCodeSessionNotFound AgentRuntimeExecutionFailureCode = "session_not_found" @@ -275,6 +276,8 @@ func (e AgentRuntimeExecutionFailureCode) Valid() bool { return true case AgentRuntimeExecutionFailureCodeRateLimited: return true + case AgentRuntimeExecutionFailureCodeReplyNotSent: + return true case AgentRuntimeExecutionFailureCodeReplyUndelivered: return true case AgentRuntimeExecutionFailureCodeResponseTooLarge: @@ -2120,6 +2123,21 @@ func (e LocalModelDownloadProgressStep) Valid() bool { } } +// Defines values for LocalModelErrorCause. +const ( + LocalModelErrorCauseGatewayHomeNotPrivate LocalModelErrorCause = "GATEWAY_HOME_NOT_PRIVATE" +) + +// Valid indicates whether the value is a known member of the LocalModelErrorCause enum. +func (e LocalModelErrorCause) Valid() bool { + switch e { + case LocalModelErrorCauseGatewayHomeNotPrivate: + return true + default: + return false + } +} + // Defines values for LocalModelErrorCode. const ( CANCELLED LocalModelErrorCode = "CANCELLED" @@ -4426,7 +4444,7 @@ type AgentRuntimeConfig struct { ReasoningEffort *AgentReasoningEffort `json:"reasoning_effort,omitempty"` } -// AgentRuntimeExecutionFailure Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. +// AgentRuntimeExecutionFailure Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. reply_not_sent means a Room Run finished without trying to post anything while a Human who mentioned the Agent waited for its reply; the Runtime ended the turn in text nobody sees, which is not posted for it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. type AgentRuntimeExecutionFailure struct { Code AgentRuntimeExecutionFailureCode `json:"code"` RuntimeType *LocalRuntimeType `json:"runtime_type,omitempty"` @@ -4495,7 +4513,7 @@ type AgentRuntimePresentationOutputCreatedEventSurface string // AgentRuntimeStoppedStatusChangedEvent defines model for AgentRuntimeStoppedStatusChangedEvent. type AgentRuntimeStoppedStatusChangedEvent struct { - // Failure Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. + // Failure Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. reply_not_sent means a Room Run finished without trying to post anything while a Human who mentioned the Agent waited for its reply; the Runtime ended the turn in text nobody sees, which is not posted for it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. Failure *AgentRuntimeExecutionFailure `json:"failure,omitempty"` Outcome AgentRuntimeStoppedStatusChangedEventOutcome `json:"outcome"` Status string `json:"status"` @@ -6060,9 +6078,12 @@ type Error struct { // ErrorDetail defines model for ErrorDetail. type ErrorDetail struct { // Code Optional stable classification for this individual validation issue. - Code *string `json:"code,omitempty"` - Field string `json:"field"` - Reason string `json:"reason"` + Code *string `json:"code,omitempty"` + Field string `json:"field"` + + // LimitBytes With code too_large, the largest size the field accepts, in bytes. + LimitBytes *int64 `json:"limit_bytes,omitempty"` + Reason string `json:"reason"` } // ErrorResponse defines model for ErrorResponse. @@ -6582,13 +6603,22 @@ type LocalModelEndpoint struct { // LocalModelError defines model for LocalModelError. type LocalModelError struct { + // Cause Why a GATEWAY_REGISTRATION_FAILED happened, when the Computer supervised the failed job. GATEWAY_HOME_NOT_PRIVATE: the local gateway's private folder at path has another owner; closing Linger and renaming that folder lets the model load. + Cause *LocalModelErrorCause `json:"cause,omitempty"` + // Code Closed localmodels library error set. It is extended only together with the localmodels library contract. Code LocalModelErrorCode `json:"code"` // Detail Diagnostic text for display; never matched on. Detail *string `json:"detail,omitempty"` + + // Path The folder the cause names, on the Computer. The public view carries it only for the Computer's owner. + Path *string `json:"path,omitempty"` } +// LocalModelErrorCause Why a GATEWAY_REGISTRATION_FAILED happened, when the Computer supervised the failed job. GATEWAY_HOME_NOT_PRIVATE: the local gateway's private folder at path has another owner; closing Linger and renaming that folder lets the model load. +type LocalModelErrorCause string + // LocalModelErrorCode Closed localmodels library error set. It is extended only together with the localmodels library contract. type LocalModelErrorCode string diff --git a/contracts/generated/typescript/src/generated/node-services-internal/types.ts b/contracts/generated/typescript/src/generated/node-services-internal/types.ts index 15046f4d2..b963a3dbd 100644 --- a/contracts/generated/typescript/src/generated/node-services-internal/types.ts +++ b/contracts/generated/typescript/src/generated/node-services-internal/types.ts @@ -1448,6 +1448,11 @@ export interface components { /** @description Optional stable classification for this individual validation issue. */ code?: string; reason: string; + /** + * Format: int64 + * @description With code too_large, the largest size the field accepts, in bytes. + */ + limit_bytes?: number; }; Error: { /** @example ROOM_NOT_FOUND */ diff --git a/contracts/generated/typescript/src/generated/runner-gateway/schema.ts b/contracts/generated/typescript/src/generated/runner-gateway/schema.ts index 9415f0802..406b5e233 100644 --- a/contracts/generated/typescript/src/generated/runner-gateway/schema.ts +++ b/contracts/generated/typescript/src/generated/runner-gateway/schema.ts @@ -2403,6 +2403,17 @@ export const runnerGatewayEnvelopeSchema = { type: "string", maxLength: 4000, }, + cause: { + description: + "Why a GATEWAY_REGISTRATION_FAILED happened, from the failed job's error line. GATEWAY_HOME_NOT_PRIVATE: the local gateway's private folder at path has another owner.", + enum: ["GATEWAY_HOME_NOT_PRIVATE"], + }, + path: { + description: "The folder the cause names.", + type: "string", + minLength: 1, + maxLength: 4096, + }, }, }, LocalModelNote: { diff --git a/contracts/generated/typescript/src/generated/runner-gateway/types.ts b/contracts/generated/typescript/src/generated/runner-gateway/types.ts index 13220df0c..622ce0b09 100644 --- a/contracts/generated/typescript/src/generated/runner-gateway/types.ts +++ b/contracts/generated/typescript/src/generated/runner-gateway/types.ts @@ -1466,6 +1466,14 @@ export interface LocalModelError { * Diagnostic text for display; never matched on. */ detail?: string; + /** + * Why a GATEWAY_REGISTRATION_FAILED happened, from the failed job's error line. GATEWAY_HOME_NOT_PRIVATE: the local gateway's private folder at path has another owner. + */ + cause?: "GATEWAY_HOME_NOT_PRIVATE"; + /** + * The folder the cause names. + */ + path?: string; } /** * Present only when idle and the automatic load after download was skipped. diff --git a/contracts/generated/typescript/src/generated/teamhub-internal/types.ts b/contracts/generated/typescript/src/generated/teamhub-internal/types.ts index 4d147fc9e..3eefbc40f 100644 --- a/contracts/generated/typescript/src/generated/teamhub-internal/types.ts +++ b/contracts/generated/typescript/src/generated/teamhub-internal/types.ts @@ -1604,6 +1604,11 @@ export interface components { /** @description Optional stable classification for this individual validation issue. */ code?: string; reason: string; + /** + * Format: int64 + * @description With code too_large, the largest size the field accepts, in bytes. + */ + limit_bytes?: number; }; Error: { /** @example ROOM_NOT_FOUND */ @@ -2107,7 +2112,7 @@ export interface components { AgentRuntimeSuccessResult: { success: boolean; }; - /** @description Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. */ + /** @description Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. reply_not_sent means a Room Run finished without trying to post anything while a Human who mentioned the Agent waited for its reply; the Runtime ended the turn in text nobody sees, which is not posted for it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. */ AgentRuntimeExecutionFailure: { /** @enum {string} */ code: @@ -2124,6 +2129,7 @@ export interface components { | "execution_failed" | "execution_outcome_unknown" | "reply_undelivered" + | "reply_not_sent" | "interrupted" | "computer_unavailable" | "cleanup_unconfirmed" @@ -2620,6 +2626,13 @@ export interface components { code: components["schemas"]["LocalModelErrorCode"]; /** @description Diagnostic text for display; never matched on. */ detail?: string; + /** + * @description Why a GATEWAY_REGISTRATION_FAILED happened, when the Computer supervised the failed job. GATEWAY_HOME_NOT_PRIVATE: the local gateway's private folder at path has another owner; closing Linger and renaming that folder lets the model load. + * @enum {string} + */ + cause?: "GATEWAY_HOME_NOT_PRIVATE"; + /** @description The folder the cause names, on the Computer. The public view carries it only for the Computer's owner. */ + path?: string; }; LocalModelNote: { /** @enum {string} */ diff --git a/contracts/generated/typescript/src/generated/teamhub-public/types.ts b/contracts/generated/typescript/src/generated/teamhub-public/types.ts index ced850530..4ec4a4d33 100644 --- a/contracts/generated/typescript/src/generated/teamhub-public/types.ts +++ b/contracts/generated/typescript/src/generated/teamhub-public/types.ts @@ -4192,6 +4192,11 @@ export interface components { /** @description Optional stable classification for this individual validation issue. */ code?: string; reason: string; + /** + * Format: int64 + * @description With code too_large, the largest size the field accepts, in bytes. + */ + limit_bytes?: number; }; Error: { /** @example ROOM_NOT_FOUND */ @@ -4683,6 +4688,13 @@ export interface components { code: components["schemas"]["LocalModelErrorCode"]; /** @description Diagnostic text for display; never matched on. */ detail?: string; + /** + * @description Why a GATEWAY_REGISTRATION_FAILED happened, when the Computer supervised the failed job. GATEWAY_HOME_NOT_PRIVATE: the local gateway's private folder at path has another owner; closing Linger and renaming that folder lets the model load. + * @enum {string} + */ + cause?: "GATEWAY_HOME_NOT_PRIVATE"; + /** @description The folder the cause names, on the Computer. The public view carries it only for the Computer's owner. */ + path?: string; }; LocalModelNote: { /** @enum {string} */ @@ -6397,7 +6409,7 @@ export interface components { /** @description Optional public queue label for queued, or the full provider-visible reasoning summary title for thinking. Omit for working; raw reasoning is never allowed. */ title?: string; }; - /** @description Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. */ + /** @description Public classified failure; contains no native error text, paths, credentials, or task input. Each code is set where the failure is observed, from structured signals only. model_unavailable means the model service refused the selected model for the Runtime's account, so the Agent needs another model or another sign-in. model_not_offered means the Agent's Computer does not offer the selected model for its Runtime, or the model does not support the selected reasoning effort, so the Runtime could not start; the Agent needs a model and reasoning effort that Computer offers. context_too_long means the conversation no longer fits the model's context window. model_service_error means the model service reported a server-side error. timeout means the Runtime hit its local execution deadline. execution_outcome_unknown means a command was dispatched but no validated exit was observed before unexpected transport or Runtime failure. Intentional cancellation, authorization loss or unavailability, and normal retirement do not create this classification. Authorization loss or unavailability includes explicit revocation, authorization checks that fail or time out, and authorization expiry. This code does not currently cover unknown effects caused by control-plane disconnection. It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. reply_not_sent means a Room Run finished without trying to post anything while a Human who mentioned the Agent waited for its reply; the Runtime ended the turn in text nobody sees, which is not posted for it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. computer_unavailable means the Agent's Computer could not run it: the Computer is unreachable, the Agent's Runner is stopped there, or the Runtime is not enabled. cleanup_unconfirmed means the Runtime process could not be confirmed stopped. response_too_large means the reply exceeded the Room's size limit. unclassified means no structured signal identified the cause. runtime_type is present when the failure belongs to a selected Runtime; it is absent for failures the Agent Service or TeamHub observes without one. */ AgentRuntimeExecutionFailure: { /** @enum {string} */ code: @@ -6414,6 +6426,7 @@ export interface components { | "execution_failed" | "execution_outcome_unknown" | "reply_undelivered" + | "reply_not_sent" | "interrupted" | "computer_unavailable" | "cleanup_unconfirmed" diff --git a/contracts/openapi/components/agent-runtime-state.yaml b/contracts/openapi/components/agent-runtime-state.yaml index d35bb9676..3a9db3248 100644 --- a/contracts/openapi/components/agent-runtime-state.yaml +++ b/contracts/openapi/components/agent-runtime-state.yaml @@ -1076,6 +1076,9 @@ components: It remains a failed Run and must not be automatically replayed; verify its effects before starting another Run. reply_undelivered means a Room Run finished, but every message the Agent tried to post failed, so the Room received no reply from it. + reply_not_sent means a Room Run finished without trying to post anything while a + Human who mentioned the Agent waited for its reply; the Runtime ended the turn in + text nobody sees, which is not posted for it. interrupted means the Run stopped before it finished for a reason other than a user cancellation, such as a restart or a Runner stopped on its Computer; part of its work may have taken effect and it is not replayed. @@ -1104,6 +1107,7 @@ components: execution_failed, execution_outcome_unknown, reply_undelivered, + reply_not_sent, interrupted, computer_unavailable, cleanup_unconfirmed, diff --git a/contracts/openapi/components/common.yaml b/contracts/openapi/components/common.yaml index 16f74425a..f2f0fb4be 100644 --- a/contracts/openapi/components/common.yaml +++ b/contracts/openapi/components/common.yaml @@ -351,6 +351,11 @@ components: reason: type: string minLength: 1 + limit_bytes: + description: With code too_large, the largest size the field accepts, in bytes. + type: integer + format: int64 + minimum: 0 Error: type: object additionalProperties: false diff --git a/contracts/openapi/components/local-models.yaml b/contracts/openapi/components/local-models.yaml index ea5bf0422..611d47ae9 100644 --- a/contracts/openapi/components/local-models.yaml +++ b/contracts/openapi/components/local-models.yaml @@ -282,6 +282,22 @@ components: description: Diagnostic text for display; never matched on. type: string maxLength: 4000 + cause: + description: >- + Why a GATEWAY_REGISTRATION_FAILED happened, when the Computer + supervised the failed job. GATEWAY_HOME_NOT_PRIVATE: the local + gateway's private folder at path has another owner; closing Linger + and renaming that folder lets the model load. + type: string + enum: [GATEWAY_HOME_NOT_PRIVATE] + x-enum-varnames: [LocalModelErrorCauseGatewayHomeNotPrivate] + path: + description: >- + The folder the cause names, on the Computer. The public view + carries it only for the Computer's owner. + type: string + minLength: 1 + maxLength: 4096 LocalModelNote: type: object additionalProperties: false diff --git a/contracts/runner-gateway/envelope.schema.json b/contracts/runner-gateway/envelope.schema.json index f67314e27..706b2a0d6 100644 --- a/contracts/runner-gateway/envelope.schema.json +++ b/contracts/runner-gateway/envelope.schema.json @@ -2380,6 +2380,16 @@ "description": "Diagnostic text for display; never matched on.", "type": "string", "maxLength": 4000 + }, + "cause": { + "description": "Why a GATEWAY_REGISTRATION_FAILED happened, from the failed job's error line. GATEWAY_HOME_NOT_PRIVATE: the local gateway's private folder at path has another owner.", + "enum": ["GATEWAY_HOME_NOT_PRIVATE"] + }, + "path": { + "description": "The folder the cause names.", + "type": "string", + "minLength": 1, + "maxLength": 4096 } } },