TypeScript Agent SDK

@siloga/magmell-agent is the small in-handler SDK for node-22 deployments. It is not a control-plane client and it does not deploy or invoke agents. Use the separate TypeScript control-plane SDK for those operations.

Staged availability

The Agent SDK and Node runtime are prepared for a controlled rollout, but the package is not yet a generally available public-registry dependency. Registry publication is a separate release event and is not represented by /v1/capabilities. Node deployment creation and dispatch may also remain disabled independently.

Add development types

The public package repository and registry are not selected yet, so there is currently no supported install command. Do not configure the internal Siloga Forgejo registry: it is not a customer package endpoint. The capability response intentionally returns install_command: null and agent_package_range: null until a reviewed package is actually published.

Cloud deployments do not need a package declaration. Magmell bundles the protected runtime SDK while compiling the handler, so imports shown below work in deployed node-22 handlers. For local type checking, use the package workspace from the Magmell repository until public distribution is announced. Once published, the docs and capability response will provide one exact supported install command together.

Read a secret

import { secret } from '@siloga/magmell-agent'

const value: string | undefined = secret('MODEL_API_KEY')

Secrets exist only during an active invocation. A missing name returns undefined. Do not cache a secret in module scope, include it in telemetry, or return it from the handler.

Write a structured log

import { log } from '@siloga/magmell-agent'

log('document received', { level: 'debug', documentId: 'doc_123' })

The supported levels are debug, default, warning, and error. Unknown levels are normalized to default.

Emit a domain event

import { event } from '@siloga/magmell-agent'

event('document.classified', { category: 'invoice' })

Emit a measurement

import { metric } from '@siloga/magmell-agent'

metric('model.tokens', 842, { model: 'example-model' })

Time asynchronous work

import { span } from '@siloga/magmell-agent'

const response = await span('model.request', () => model.generate(prompt))

span resolves to the operation’s value and emits its duration whether the operation resolves or rejects.

Invocation isolation

The Node.js 22 runtime stores helper state in AsyncLocalStorage. Secrets and events follow the active asynchronous call chain without being shared by overlapping invocations. Your own module globals remain shared, so keep invocation-specific state in local variables.

Telemetry data is normalized into bounded JSON immediately. Circular, non-finite, unreadable, or oversized values become diagnostic markers rather than breaking the entire invocation.