{"_id":"@arlopass/adapter-runtime","name":"@arlopass/adapter-runtime","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@arlopass/adapter-runtime","version":"0.1.0","license":"MIT","type":"module","publishConfig":{"access":"public","provenance":true},"repository":{"type":"git","url":"git+https://github.com/arlopass/arlopass.git","directory":"adapters/runtime"},"homepage":"https://github.com/arlopass/arlopass/tree/main/adapters/runtime#readme","bugs":{"url":"https://github.com/arlopass/arlopass/issues"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","lint":"eslint \"src/**/*.ts\"","test":"vitest run --passWithNoTests"},"dependencies":{"@arlopass/policy":"workspace:*","@arlopass/protocol":"workspace:*","@arlopass/telemetry":"workspace:*"},"_id":"@arlopass/adapter-runtime@0.1.0","gitHead":"524008c81190adecca51ec54fbe99d77ebdd056f","description":"Load, host, sandbox, and health-check Arlopass provider adapters. Manages the full lifecycle from manifest validation through sandboxed execution.","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-qxkCjoftRIwsyIcZyewSKjNUih7l/qQuIpxmDTFk8w2Q1kljJ6y6vKSsukIbWpB41tYZZrWCuIzP3DENqF+hwg==","shasum":"2928c53fade040e208662dbb84177433207f1307","tarball":"https://registry.npmjs.org/@arlopass/adapter-runtime/-/adapter-runtime-0.1.0.tgz","fileCount":34,"unpackedSize":130802,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@arlopass%2fadapter-runtime@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBJ1qi1ZZZyXVQkrNCmmAKuqhUwN/n2q/4uzEh7n3PWSAiBl8ivWNHNdEp9ch1QXyBpAj9h4wAG7casd6HN91WIuMw=="}]},"_npmUser":{"name":"davidszakacs","email":"szakacs_david@hotmail.com"},"directories":{},"maintainers":[{"name":"davidszakacs","email":"szakacs_david@hotmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/adapter-runtime_0.1.0_1774820861847_0.6794133696490321"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T21:47:41.767Z","0.1.0":"2026-03-29T21:47:41.974Z","modified":"2026-03-29T21:47:42.298Z"},"maintainers":[{"name":"davidszakacs","email":"szakacs_david@hotmail.com"}],"description":"Load, host, sandbox, and health-check Arlopass provider adapters. Manages the full lifecycle from manifest validation through sandboxed execution.","homepage":"https://github.com/arlopass/arlopass/tree/main/adapters/runtime#readme","repository":{"type":"git","url":"git+https://github.com/arlopass/arlopass.git","directory":"adapters/runtime"},"bugs":{"url":"https://github.com/arlopass/arlopass/issues"},"license":"MIT","readme":"# @arlopass/adapter-runtime\n\nLoad, host, sandbox, and health-check Arlopass provider adapters. Manages the full lifecycle from manifest validation through sandboxed execution.\n\n```ts\nimport { loadAdapter, AdapterHost } from \"@arlopass/adapter-runtime\";\n\nconst loaded = await loadAdapter(manifestJson, () => new OllamaAdapter(), {\n  requireSignatureVerification: false,\n});\n\nconst host = new AdapterHost();\nawait host.start();\nawait host.registerAdapter(loaded);\n\nconst health = host.getAdapterHealth(\"ollama\");\nconsole.log(health.state); // \"running\"\n\nconst response = await host.callAdapter(\"ollama\", async (adapter, sandbox) => {\n  return adapter.contract.sendMessage(\"session-1\", \"Hello\");\n});\n\nawait host.shutdown();\n```\n\n---\n\n## API Reference\n\n### `AdapterContract`\n\nInterface every adapter must implement:\n\n```ts\ninterface AdapterContract {\n  readonly manifest: AdapterManifest;\n  describeCapabilities(): readonly ProtocolCapability[];\n  listModels(): Promise<readonly string[]>;\n  createSession(options?: Record<string, unknown>): Promise<string>;\n  sendMessage(sessionId: string, message: string): Promise<string>;\n  streamMessage(sessionId: string, message: string, onChunk: (chunk: string) => void): Promise<void>;\n  healthCheck(): Promise<boolean>;\n  shutdown(): Promise<void>;\n}\n```\n\n### `CloudAdapterContractV2`\n\nExtended contract for cloud providers with connection lifecycle:\n\n```ts\ninterface CloudAdapterContractV2 extends AdapterContract {\n  listConnectionMethods(): readonly ConnectionMethodDescriptor[];\n  beginConnect(input: BeginConnectInput): Promise<BeginConnectResult>;\n  completeConnect(input: CompleteConnectInput): Promise<CompleteConnectResult>;\n  validateCredentialRef(input: ValidateCredentialRefInput): Promise<ValidationResult>;\n  revokeCredentialRef(input: RevokeCredentialRefInput): Promise<void>;\n  discoverModels(ctx: CloudConnectionContext): Promise<readonly ModelDescriptor[]>;\n  discoverCapabilities(ctx: CloudConnectionContext): Promise<CapabilityDescriptor>;\n}\n```\n\n**`isCloudAdapterContractV2(candidate: unknown): boolean`** — Type guard.\n\n---\n\n### `AdapterManifest`\n\nDeclarative manifest every adapter ships:\n\n```ts\ntype AdapterManifest = {\n  schemaVersion: string;                              // \"1.0.0\"\n  providerId: string;\n  version: string;\n  displayName: string;\n  authType: \"none\" | \"api_key\" | \"oauth2\" | \"local\";\n  capabilities: readonly ProtocolCapability[];\n  requiredPermissions: readonly string[];\n  egressRules: readonly AdapterEgressRule[];\n  riskLevel: \"low\" | \"medium\" | \"high\";\n  signingKeyId: string;\n  connectionMethods?: readonly ConnectionMethodDescriptor[];\n  metadata?: Record<string, string>;\n}\n\ntype AdapterEgressRule = { host: string; port?: number; protocol: \"https\" | \"http\" | \"tcp\" }\n```\n\n| Function | Description |\n|----------|-------------|\n| `parseAdapterManifest(input: unknown): AdapterManifest` | Parse and validate, throws `ManifestValidationError` |\n| `safeParseAdapterManifest(input: unknown): SafeParseResult<AdapterManifest>` | Non-throwing variant |\n| `isAdapterManifest(input: unknown): boolean` | Type guard |\n| `parseConnectionMethods(input: unknown, options?): readonly ConnectionMethodDescriptor[]` | Parse connection method descriptors |\n\n---\n\n### `AdapterHost`\n\nManages running adapters with health checks, restart logic, and sandbox enforcement.\n\n```ts\nconst host = new AdapterHost(options?: AdapterHostOptions);\n```\n\n| Method | Returns | Description |\n|--------|---------|-------------|\n| `start()` | `Promise<void>` | Start the host runtime |\n| `registerAdapter(loaded)` | `Promise<void>` | Register a loaded adapter |\n| `deregisterAdapter(providerId)` | `Promise<void>` | Remove an adapter |\n| `getAdapterHealth(providerId)` | `AdapterHealthStatus` | Get adapter health |\n| `listAdapterHealth()` | `readonly AdapterHealthStatus[]` | Health of all adapters |\n| `getManifest(providerId)` | `AdapterManifest` | Get adapter manifest |\n| `getSandboxContext(providerId)` | `SandboxContext` | Get sandbox context |\n| `callAdapter(providerId, fn)` | `Promise<T>` | Execute within adapter sandbox |\n| `shutdown()` | `Promise<void>` | Stop all adapters |\n| `isStarted` | `boolean` | Whether host is running |\n\n```ts\ntype AdapterState = \"pending\" | \"starting\" | \"running\" | \"degraded\" | \"stopped\" | \"failed\"\n\ntype AdapterHealthStatus = {\n  state: AdapterState;\n  providerId: string;\n  lastHealthCheck?: string;\n  restartCount: number;\n  error?: string;\n}\n```\n\n---\n\n### `loadAdapter(manifestInput, factory, options?): Promise<LoadedAdapter>`\n\nLoad and validate an adapter from its manifest and factory function.\n\nStrict cloud-contract enforcement is opt-in via manifest:\n\n- If `connectionMethods` contains one or more descriptors, the contract must satisfy `CloudAdapterContractV2`, and `listConnectionMethods()` must match the manifest descriptors exactly.\n- If `connectionMethods` is omitted (or present but empty), runtime preserves legacy compatibility and only requires `AdapterContract`.\n\n```ts\ntype LoadedAdapter = {\n  providerId: string;\n  manifest: AdapterManifest;\n  contract: AdapterContract;\n}\n```\n\n---\n\n### Artifact Signing\n\nSign and verify adapter artifacts with Ed25519:\n\n| Function | Description |\n|----------|-------------|\n| `signArtifact(payload, options): SignedArtifact` | Sign an adapter artifact |\n| `verifyArtifactSignature(artifact, options): ArtifactVerificationResult` | Verify signature against key resolver |\n| `computeArtifactDigest(content): string` | Compute content digest |\n| `parseArtifactSignature(input): ArtifactSignature` | Parse a raw signature |\n| `canonicalizeArtifactPayload(artifact): string` | Canonical form for signing |\n\n```ts\ntype SignedArtifact = {\n  providerId: string;\n  version: string;\n  digest: string;\n  signature: ArtifactSignature;\n}\n\ntype ArtifactSignature = {\n  algorithm: \"ed25519\";\n  keyId: string;\n  signedAt: string;\n  digest: string;\n  value: string;\n}\n\ninterface ArtifactKeyResolver {\n  resolvePublicKey(keyId: string): string | undefined;\n}\n```\n\n---\n\n### Error Classes\n\n| Class | Description |\n|-------|-------------|\n| `RuntimeError` | Base class (has `code`, `details`) |\n| `ManifestValidationError` | Invalid manifest (has `field`) |\n| `SignatureVerificationError` | Artifact signature check failed |\n| `SandboxViolationError` | Adapter violated sandbox constraints |\n| `AdapterLoaderError` | Failed to load adapter |\n| `AdapterHostError` | Host runtime failure |\n\nError codes are defined in `RUNTIME_ERROR_CODES` (30+ codes covering manifest, signature, sandbox, loader, and host errors).\n\n---\n\n### Constants\n\n| Constant | Value |\n|----------|-------|\n| `MANIFEST_SCHEMA_VERSION` | `\"1.0.0\"` |\n| `ARTIFACT_SIGNATURE_ALGORITHM` | `\"ed25519\"` |\n| `ADAPTER_AUTH_TYPES` | `{ NONE, API_KEY, OAUTH2, LOCAL }` |\n| `ADAPTER_RISK_LEVELS` | `{ LOW, MEDIUM, HIGH }` |\n| `ADAPTER_STATE` | `{ PENDING, STARTING, RUNNING, DEGRADED, STOPPED, FAILED }` |\n\n---\n\n### Dependencies\n\n- `@arlopass/protocol` — Capability model, error taxonomy\n- `@arlopass/policy` — Permission and egress validation\n- `@arlopass/telemetry` — Health and performance metrics\n","readmeFilename":"README.md","_rev":"1-674507cce0740ccccede38a0b128d5f4"}