2026-03-17 09:24:28 -05:00
|
|
|
import type {
|
|
|
|
|
InstanceExperimentalSettings,
|
2026-03-20 08:00:39 -05:00
|
|
|
InstanceGeneralSettings,
|
[codex] Add configurable liveness auto-recovery controls (#4587)
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies.
> - Heartbeat liveness recovery decides when stalled issue trees need
manager-visible follow-up.
> - Automatic recovery issue creation is useful, but operators need
instance-level controls for how aggressive it is.
> - Without controls, recovery behavior is harder to tune for local
development, production operations, and noisy edge cases.
> - This pull request adds configurable liveness auto-recovery settings
across shared contracts, API routes, services, and the instance
experimental settings UI.
> - The benefit is that operators can keep liveness findings advisory or
enable bounded recovery automation with explicit intervals and lookback
windows.
## What Changed
- Added shared types and validators for liveness auto-recovery settings.
- Extended instance settings routes and services to persist and validate
the new controls.
- Wired heartbeat/recovery services to honor enablement, minimum
interval, and lookback settings.
- Added UI controls for liveness recovery under instance experimental
settings.
- Covered the new server behavior with instance settings and liveness
escalation tests.
## Verification
- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/heartbeat-issue-liveness-escalation.test.ts
server/src/__tests__/instance-settings-routes.test.ts --pool=forks
--poolOptions.forks.isolate=true`
- `pnpm --filter @paperclipai/shared typecheck`
- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/ui typecheck`
## Risks
- Moderate behavioral risk because recovery automation timing changes
when enabled; defaults keep existing advisory behavior unless the
setting is turned on.
- No database migration in this PR; settings are stored through the
existing instance settings path.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- OpenAI Codex, `gpt-5`, coding model with tool use and local command
execution; context window not exposed by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-04-27 08:46:44 -05:00
|
|
|
IssueGraphLivenessAutoRecoveryPreview,
|
2026-03-20 08:00:39 -05:00
|
|
|
PatchInstanceGeneralSettings,
|
2026-03-17 09:24:28 -05:00
|
|
|
PatchInstanceExperimentalSettings,
|
|
|
|
|
} from "@paperclipai/shared";
|
|
|
|
|
import { api } from "./client";
|
|
|
|
|
|
|
|
|
|
export const instanceSettingsApi = {
|
2026-03-20 08:00:39 -05:00
|
|
|
getGeneral: () =>
|
|
|
|
|
api.get<InstanceGeneralSettings>("/instance/settings/general"),
|
|
|
|
|
updateGeneral: (patch: PatchInstanceGeneralSettings) =>
|
|
|
|
|
api.patch<InstanceGeneralSettings>("/instance/settings/general", patch),
|
2026-03-17 09:24:28 -05:00
|
|
|
getExperimental: () =>
|
|
|
|
|
api.get<InstanceExperimentalSettings>("/instance/settings/experimental"),
|
|
|
|
|
updateExperimental: (patch: PatchInstanceExperimentalSettings) =>
|
|
|
|
|
api.patch<InstanceExperimentalSettings>("/instance/settings/experimental", patch),
|
[codex] Add configurable liveness auto-recovery controls (#4587)
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies.
> - Heartbeat liveness recovery decides when stalled issue trees need
manager-visible follow-up.
> - Automatic recovery issue creation is useful, but operators need
instance-level controls for how aggressive it is.
> - Without controls, recovery behavior is harder to tune for local
development, production operations, and noisy edge cases.
> - This pull request adds configurable liveness auto-recovery settings
across shared contracts, API routes, services, and the instance
experimental settings UI.
> - The benefit is that operators can keep liveness findings advisory or
enable bounded recovery automation with explicit intervals and lookback
windows.
## What Changed
- Added shared types and validators for liveness auto-recovery settings.
- Extended instance settings routes and services to persist and validate
the new controls.
- Wired heartbeat/recovery services to honor enablement, minimum
interval, and lookback settings.
- Added UI controls for liveness recovery under instance experimental
settings.
- Covered the new server behavior with instance settings and liveness
escalation tests.
## Verification
- `pnpm exec vitest run --project @paperclipai/server
server/src/__tests__/heartbeat-issue-liveness-escalation.test.ts
server/src/__tests__/instance-settings-routes.test.ts --pool=forks
--poolOptions.forks.isolate=true`
- `pnpm --filter @paperclipai/shared typecheck`
- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/ui typecheck`
## Risks
- Moderate behavioral risk because recovery automation timing changes
when enabled; defaults keep existing advisory behavior unless the
setting is turned on.
- No database migration in this PR; settings are stored through the
existing instance settings path.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- OpenAI Codex, `gpt-5`, coding model with tool use and local command
execution; context window not exposed by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-04-27 08:46:44 -05:00
|
|
|
previewIssueGraphLivenessAutoRecovery: (input: { lookbackHours?: number }) =>
|
|
|
|
|
api.post<IssueGraphLivenessAutoRecoveryPreview>(
|
|
|
|
|
"/instance/settings/experimental/issue-graph-liveness-auto-recovery/preview",
|
|
|
|
|
input,
|
|
|
|
|
),
|
|
|
|
|
runIssueGraphLivenessAutoRecovery: (input: { lookbackHours?: number }) =>
|
|
|
|
|
api.post<{
|
|
|
|
|
findings: number;
|
|
|
|
|
autoRecoveryEnabled: boolean;
|
|
|
|
|
lookbackHours: number;
|
|
|
|
|
cutoff: string;
|
|
|
|
|
escalationsCreated: number;
|
|
|
|
|
existingEscalations: number;
|
|
|
|
|
skipped: number;
|
|
|
|
|
skippedAutoRecoveryDisabled: number;
|
|
|
|
|
skippedOutsideLookback: number;
|
|
|
|
|
escalationIssueIds: string[];
|
|
|
|
|
}>(
|
|
|
|
|
"/instance/settings/experimental/issue-graph-liveness-auto-recovery/run",
|
|
|
|
|
input,
|
|
|
|
|
),
|
2026-03-17 09:24:28 -05:00
|
|
|
};
|