Files
start-os/sdk/package/lib/mainFn/Daemon.ts
Aiden McClelland f2142f0bb3 add documentation for ai agents (#3115)
* add documentation for ai agents

* docs: consolidate CLAUDE.md and CONTRIBUTING.md, add style guidelines

- Refactor CLAUDE.md to reference CONTRIBUTING.md for build/test/format info
- Expand CONTRIBUTING.md with comprehensive build targets, env vars, and testing
- Add code style guidelines section with conventional commits
- Standardize SDK prettier config to use single quotes (matching web)
- Add project-level Claude Code settings to disable co-author attribution

* style(sdk): apply prettier with single quotes

Run prettier across sdk/base and sdk/package to apply the
standardized quote style (single quotes matching web).

* docs: add USER.md for per-developer TODO filtering

- Add agents/USER.md to .gitignore (contains user identifier)
- Document session startup flow in CLAUDE.md:
  - Create USER.md if missing, prompting for identifier
  - Filter TODOs by @username tags
  - Offer relevant TODOs on session start

* docs: add i18n documentation task to agent TODOs

* docs: document i18n ID patterns in core/

Add agents/i18n-patterns.md covering rust-i18n setup, translation file
format, t!() macro usage, key naming conventions, and locale selection.
Remove completed TODO item and add reference in CLAUDE.md.

* chore: clarify that all builds work on any OS with Docker
2026-02-06 00:10:16 +01:00

143 lines
4.3 KiB
TypeScript

import * as T from '../../../base/lib/types'
import { asError } from '../../../base/lib/util/asError'
import { Drop } from '../util'
import {
SubContainer,
SubContainerOwned,
SubContainerRc,
} from '../util/SubContainer'
import { CommandController } from './CommandController'
import { DaemonCommandType } from './Daemons'
import { Oneshot } from './Oneshot'
const TIMEOUT_INCREMENT_MS = 1000
const MAX_TIMEOUT_MS = 30000
/**
* This is a wrapper around CommandController that has a state of off, where the command shouldn't be running
* and the others state of running, where it will keep a living running command
*/
export class Daemon<
Manifest extends T.SDKManifest,
C extends SubContainer<Manifest> | null = SubContainer<Manifest> | null,
> extends Drop {
private commandController: CommandController<Manifest, C> | null = null
private shouldBeRunning = false
protected exitedSuccess = false
private exiting: Promise<void> | null = null
private onExitFns: ((success: boolean) => void)[] = []
protected constructor(
private subcontainer: C,
private startCommand: () => Promise<CommandController<Manifest, C>>,
readonly oneshot: boolean = false,
) {
super()
}
isOneshot(): this is Oneshot<Manifest> {
return this.oneshot
}
static of<Manifest extends T.SDKManifest>() {
return <C extends SubContainer<Manifest> | null>(
effects: T.Effects,
subcontainer: C,
exec: DaemonCommandType<Manifest, C>,
) => {
let subc: SubContainer<Manifest> | null = subcontainer
if (subcontainer && subcontainer.isOwned()) subc = subcontainer.rc()
const startCommand = () =>
CommandController.of<Manifest, C>()(
effects,
(subc?.rc() ?? null) as C,
exec,
)
const res = new Daemon(subc, startCommand)
effects.onLeaveContext(() => {
res.term({ destroySubcontainer: true }).catch((e) => console.error(e))
})
return res
}
}
async start() {
if (this.commandController) {
return
}
this.shouldBeRunning = true
let timeoutCounter = 0
;(async () => {
while (this.shouldBeRunning) {
if (this.commandController)
await this.commandController
.term({})
.catch((err) => console.error(err))
try {
this.commandController = await this.startCommand()
if (!this.shouldBeRunning) {
// handles race condition if stopped while starting
await this.term()
break
}
const success = await this.commandController.wait().then(
(_) => true,
(err) => {
console.error(err)
return false
},
)
for (const fn of this.onExitFns) {
try {
fn(success)
} catch (e) {
console.error('EXIT handler', e)
}
}
if (success && this.oneshot) {
this.exitedSuccess = true
break
}
} catch (e) {
console.error(e)
}
await new Promise((resolve) => setTimeout(resolve, timeoutCounter))
timeoutCounter += TIMEOUT_INCREMENT_MS
timeoutCounter = Math.min(MAX_TIMEOUT_MS, timeoutCounter)
}
})().catch((err) => {
console.error(asError(err))
})
}
async term(termOptions?: {
signal?: NodeJS.Signals | undefined
timeout?: number | undefined
destroySubcontainer?: boolean
}) {
this.shouldBeRunning = false
this.exitedSuccess = false
if (this.commandController) {
this.exiting = this.commandController.term({ ...termOptions })
this.commandController = null
this.onExitFns = []
}
if (this.exiting) {
await this.exiting.catch(console.error)
if (termOptions?.destroySubcontainer) {
await this.subcontainer?.destroy()
}
this.exiting = null
}
}
subcontainerRc(): SubContainerRc<Manifest> | null {
return this.subcontainer?.rc() ?? null
}
sharesSubcontainerWith(
other: Daemon<Manifest, SubContainer<Manifest> | null>,
): boolean {
return this.subcontainer?.guid === other.subcontainer?.guid
}
onExit(fn: (success: boolean) => void) {
this.onExitFns.push(fn)
}
onDrop(): void {
this.term().catch((e) => console.error(asError(e)))
}
}