Merge pull request #213 from Deep-CodeAI/feat/4518-oasf-record-export

feat(#4518): OASF 1.0.0 record export — toOasfRecord() (AGNTCY interop, slice 1)

Author: Skobeltsyn

CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to Agents.KT are documented here. The format follows [Keep a
 
 ## [Unreleased]
 
+### Added — OASF 1.0.0 record export: `toOasfRecord()` (#4518, PRD §12.6) — AGNTCY interop, slice 1
+
+`agent.toOasfRecord(version, authors, locators, …)` emits an [OASF](https://github.com/agntcy/oasf) 1.0.0
+record — AGNTCY's content-addressed discovery metadata — the **third discovery exporter** beside the A2A
+AgentCard (`toAgentCard()`, §12.5) and native `agent.json` (`toAgentJson()`, §12.2), and the first piece of
+the AGNTCY epic (#4517: OASF + DIR + Identity-verify). The native typed agent stays the source of truth; this
+is a projection over it. OASF skills are taxonomy entries, not free text: a skill becomes an OASF `skills[]`
+entry only when annotated with `.oasf("agent_orchestration/multi_agent_planning")`, resolved to its uid via
+the vendored `OasfTaxonomy` (a `path → uid` lookup — OASF uids are explicitly assigned per node, not a single
+formula; un-annotated/unknown skills are omitted with a logged warning). Deterministic and byte-stable:
+`createdAt`/`authors`/`locators` are caller-supplied (no hidden `now()`). `toAgentJson()` gained the same
+optional provenance fields additively (`metadata.authors`, `metadata.createdAt`, `spec.locators`) — existing
+callers serialize byte-identically. New package `agents_engine.agntcy` (`toOasfRecord`, `OasfTaxonomy`,
+`OasfLocator`). **Slice 1** seeds the confirmed core of the skills taxonomy; **slice 2** (follow-up in #4518)
+vendors the complete `agntcy/oasf` trees + a build-time cross-check. 5 tests. Record signing, OASF
+import/validate, the DIR client, and Identity-verify are the remaining #4517 subtasks.
+
 ### Added — `NlWebServer`: serve agents.kt as an NLWeb endpoint (#4542, PRD §12.9)
 
 The serve side of NLWeb (the `nlwebSearch` tool, #4541, is the consume side). `NlWebServer.from(agent).start()`

docs/prd.md

@@ -2855,7 +2855,7 @@ Any node in the delegation tree can be exported as an A2A endpoint:
 project.toAgentCard(url = "https://api.deep-code.ai/agents/project")
 ```
 
-### 12.6 AGNTCY Interoperability *(planned)*
+### 12.6 AGNTCY Interoperability *(in progress — OASF record export shipped, slice 1; DIR + Identity-verify planned)*
 
 [AGNTCY](https://github.com/agntcy) — the Linux Foundation "Internet of Agents" collective (Cisco/Outshift-led) — is the second cross-vendor interop stack alongside Google A2A (§12.5). Agents.KT targets **both**: A2A is the wire/invocation standard; AGNTCY adds a content-addressed **directory** and a **trust** layer. The native, typed `agent.json` (§12.2) stays the source of truth; AGNTCY support is a set of **exporters/clients over it**, exactly parallel to `toAgentCard()`.
 
@@ -2871,19 +2871,20 @@ project.toAgentCard(url = "https://api.deep-code.ai/agents/project")
 
 So AGNTCY interop = **OASF + DIR + Identity-verify**, riding on the A2A we already do.
 
-**OASF record export/import.** A third discovery exporter beside A2A:
+**OASF record export/import.** A third discovery exporter beside A2A — **shipped (slice 1, #4518)**:
 
 ```kotlin
 val record = specMaster.toOasfRecord(
     version = "2.0.0",
     authors = listOf("K.Skobeltsyn <konstantin@skobeltsyn.com>"),
-    locators = listOf(Locator.sourceCode("https://github.com/Deep-CodeAI/Agents.KT")),
+    locators = listOf(OasfLocator("source_code", listOf("https://github.com/Deep-CodeAI/Agents.KT"))),
+    createdAt = "2026-06-15T00:00:00Z", // caller-supplied — keeps the record byte-stable
 )
-// → OASF 1.0.0 JSON: name, version, schema_version, authors, created_at,
-//   skills:[{name,id}], domains:[{name,id}], locators:[...], modules:[]
+// → OASF 1.0.0 JSON: name, version, schema_version, description?, authors, created_at?,
+//   skills:[{name,id}], domains:[{name,id}], locators:[{type,urls}], modules:[], annotations
 ```
 
-The one real engineering cost is the **skills/domains taxonomy**: OASF skills are not free text — each is `{name: "agent_orchestration/task_decomposition", id: 1001}`, where `id` is digit-concatenation of the hierarchy UIDs. No JVM SDK and no fuzzy matcher exist. Plan: **vendor** the `schema/skills` + `schema/domains` trees and compute IDs locally (offline, reproducible), with the hosted schema server (`schema.oasf.outshift.com/api/skills`) as a validation cross-check. Free-form agent skills map via an opt-in `.oasf("agent_orchestration/task_decomposition")` annotation; un-annotated skills export under a sensible default and a validation warning. Record **signing** (Sigstore/cosign over OCI) is external to the record JSON — a later optional integration, not part of the serializer.
+The one real engineering cost is the **skills/domains taxonomy**: OASF skills are not free text — each is `{name: "agent_orchestration/multi_agent_planning", id: 1003}`. Note the `id` is **not** a single digit-concatenation formula as first assumed — the uids are *explicitly assigned per node* (top-level categories are multiples of 100, but level-2 is `category + n` while level-3 is `level2*100 + nn`), so the correct mechanism is a **vendored `path → uid` lookup**, not a computation. Plan: **vendor** the `schema/skills` + `schema/domains` trees (resource TSVs) and resolve IDs by lookup, with the hosted schema server (`schema.oasf.outshift.com/api/skills`) as a build-time validation cross-check. Free-form agent skills map via an opt-in `.oasf("agent_orchestration/multi_agent_planning")` annotation on the skill; un-annotated (and unknown-path) skills are omitted from the OASF `skills[]` with a logged warning (they remain in the free-form `agent.json`). Slice 1 ships the exporter + the confirmed core of the taxonomy; **slice 2** vendors the complete trees + the cross-check. Record **signing** (Sigstore/cosign over OCI) is external to the record JSON — a later optional integration, not part of the serializer.
 
 **DIR client.** `buf generate buf.build/agntcy/dir` → grpc-kotlin stubs for `StoreService.{Push,Pull,Lookup}` (CID-addressed) and `RoutingService`/`SearchService`. DIR carries our OASF record as an opaque `google.protobuf.Struct`, so the JSON is enough — no OASF protos required. Auth is layered and optional (insecure dev / SPIFFE / OIDC bearer). Targets both self-hosted (`localhost:8888`) and the hosted network (`prod.api.ads.outshift.io`, auth-gated via hub login).
 

src/main/kotlin/agents_engine/agntcy/OasfLocator.kt

@@ -0,0 +1,12 @@
+package agents_engine.agntcy
+
+/**
+ * `agents_engine/agntcy/OasfLocator.kt` — #4518 (PRD §12.6). An OASF record `locator`: where the
+ * agent's artifact can be obtained. [type] is the OASF locator type (e.g. `"source_code"`,
+ * `"docker_image"`, `"binary"`, `"helm_chart"`); [urls] are the addresses for that type. Serialized
+ * verbatim into the OASF record's `locators[]` and (additively) into `agent.json`'s `spec.locators`.
+ */
+data class OasfLocator(
+    val type: String,
+    val urls: List<String>,
+)

src/main/kotlin/agents_engine/agntcy/OasfRecord.kt

@@ -0,0 +1,77 @@
+package agents_engine.agntcy
+
+import agents_engine.core.Agent
+import agents_engine.mcp.McpJson
+import java.util.logging.Logger
+
+private val log: Logger = Logger.getLogger("agents_engine.agntcy.OasfRecord")
+
+/**
+ * `agents_engine/agntcy/OasfRecord.kt` — #4518 (PRD §12.6). Serialize an [Agent] to an
+ * [OASF](https://github.com/agntcy/oasf) 1.0.0 record: AGNTCY's content-addressed discovery metadata,
+ * the third exporter beside the A2A AgentCard (`toAgentCard()`, §12.5) and native `agent.json`
+ * (`toAgentJson`, §12.2). The native typed agent stays the source of truth; this is a projection over
+ * it, exactly parallel to `toAgentCard()`.
+ *
+ * **Skills are taxonomy entries, not free text.** Only skills annotated with `.oasf("path")` (see
+ * [agents_engine.core.Skill.oasf]) become OASF `skills[]` — each resolved to its uid via
+ * [OasfTaxonomy]. Un-annotated skills, and annotated paths not in the vendored taxonomy, are omitted
+ * with a logged warning (they're still in `agent.json`, which carries free-form skills).
+ *
+ * **Determinism.** Keys are emitted in a fixed order and the same inputs serialize byte-identically.
+ * Wall-clock fields ([createdAt]) and authorship ([authors], [locators]) are caller-supplied rather
+ * than sampled, so the record stays reproducible (no hidden `now()`).
+ *
+ * Record signing (Sigstore/cosign over OCI) is external to the record JSON and is deferred (PRD §12.6).
+ */
+fun Agent<*, *>.toOasfRecord(
+    version: String,
+    authors: List<String> = emptyList(),
+    locators: List<OasfLocator> = emptyList(),
+    domains: List<String> = emptyList(),
+    description: String? = null,
+    createdAt: String? = null,
+    annotations: Map<String, String> = emptyMap(),
+): String {
+    val skillRecords = skills.values
+        .sortedBy { it.name }
+        .mapNotNull { skill ->
+            val path = skill.oasfPath
+            if (path == null) {
+                log.warning("OASF: skill \"${skill.name}\" has no .oasf(path) — omitted from OASF skills[].")
+                return@mapNotNull null
+            }
+            val uid = OasfTaxonomy.skillUid(path)
+            if (uid == null) {
+                log.warning("OASF: skill \"${skill.name}\" path \"$path\" not in vendored OASF taxonomy — omitted.")
+                return@mapNotNull null
+            }
+            linkedMapOf<String, Any?>("name" to path, "id" to uid)
+        }
+
+    val domainRecords = domains
+        .sorted()
+        .mapNotNull { path ->
+            val uid = OasfTaxonomy.domainUid(path)
+            if (uid == null) {
+                log.warning("OASF: domain \"$path\" is not in the vendored OASF taxonomy — omitted.")
+                return@mapNotNull null
+            }
+            linkedMapOf<String, Any?>("name" to path, "id" to uid)
+        }
+
+    val record = LinkedHashMap<String, Any?>()
+    record["name"] = name
+    record["version"] = version
+    record["schema_version"] = OasfTaxonomy.SCHEMA_VERSION
+    if (description != null) record["description"] = description
+    record["authors"] = authors
+    if (createdAt != null) record["created_at"] = createdAt
+    record["skills"] = skillRecords
+    record["domains"] = domainRecords
+    record["locators"] = locators.map { linkedMapOf<String, Any?>("type" to it.type, "urls" to it.urls) }
+    record["modules"] = emptyList<Any?>()
+    record["annotations"] = annotations
+
+    return McpJson.encode(record)
+}

src/main/kotlin/agents_engine/agntcy/OasfTaxonomy.kt

@@ -0,0 +1,44 @@
+package agents_engine.agntcy
+
+/**
+ * `agents_engine/agntcy/OasfTaxonomy.kt` — #4518 (PRD §12.6). The vendored OASF 1.0.0 skills/domains
+ * taxonomy, loaded from the `oasf/skills-*.tsv` / `oasf/domains-*.tsv` resources. OASF skills/domains
+ * are not free text: each is a
+ * `{name, id}` where `id` is the taxonomy uid. The uids are explicitly assigned per node (top-level
+ * categories are multiples of 100; deeper levels follow a per-level breadcrumb), so this is a lookup
+ * table, not a computed formula — `path -> uid`, resolved offline and reproducibly.
+ *
+ * Slice 1 seeds the confirmed core of the tree; slice 2 vendors the complete `agntcy/oasf` schema and
+ * adds a build-time cross-check against `schema.oasf.outshift.com`. Unknown paths resolve to `null`,
+ * which `toOasfRecord` treats as "free-form skill" (omitted from the OASF record with a warning).
+ */
+object OasfTaxonomy {
+    const val SCHEMA_VERSION: String = "1.0.0"
+
+    private val skills: Map<String, Int> = loadTsv("/oasf/skills-1.0.0.tsv")
+    private val domains: Map<String, Int> = loadTsv("/oasf/domains-1.0.0.tsv")
+
+    /** Resolve an OASF skill path (e.g. `"agent_orchestration/multi_agent_planning"`) to its uid, or null. */
+    fun skillUid(path: String): Int? = skills[path.trim().trim('/')]
+
+    /** Resolve an OASF domain path to its uid, or null. */
+    fun domainUid(path: String): Int? = domains[path.trim().trim('/')]
+
+    private fun loadTsv(resource: String): Map<String, Int> {
+        val text = OasfTaxonomy::class.java.getResourceAsStream(resource)?.bufferedReader()?.use { it.readText() }
+            ?: error("OASF taxonomy resource missing: $resource")
+        val map = LinkedHashMap<String, Int>()
+        text.lineSequence().forEach { raw ->
+            val line = raw.trim()
+            if (line.isEmpty() || line.startsWith("#")) return@forEach
+            val tab = line.indexOf('\t')
+            require(tab > 0) { "Malformed OASF taxonomy line in $resource: \"$raw\" (expected <path>\\t<uid>)" }
+            val path = line.substring(0, tab).trim()
+            val uid = line.substring(tab + 1).trim().toIntOrNull()
+                ?: error("Non-numeric uid in $resource: \"$raw\"")
+            require(path !in map) { "Duplicate OASF path in $resource: \"$path\"" }
+            map[path] = uid
+        }
+        return map
+    }
+}

src/main/kotlin/agents_engine/core/AgentJson.kt

@@ -1,5 +1,6 @@
 package agents_engine.core
 
+import agents_engine.agntcy.OasfLocator
 import agents_engine.mcp.McpJson
 
 /**
@@ -10,12 +11,24 @@ import agents_engine.mcp.McpJson
  * description of the agent itself.
  *
  * Keys are emitted in a fixed order, so the same agent always serializes byte-identically.
+ *
+ * #4518 (PRD §12.6) — optional provenance fields ([authors], [createdAt], [locators]) are shared with
+ * the OASF record (`toOasfRecord`); they are additive and omitted when not supplied, so existing
+ * callers serialize byte-identically.
  */
-fun Agent<*, *>.toAgentJson(version: String? = null, description: String? = null): String {
+fun Agent<*, *>.toAgentJson(
+    version: String? = null,
+    description: String? = null,
+    authors: List<String> = emptyList(),
+    createdAt: String? = null,
+    locators: List<OasfLocator> = emptyList(),
+): String {
     val metadata = LinkedHashMap<String, Any?>()
     metadata["name"] = name
     if (version != null) metadata["version"] = version
     if (description != null) metadata["description"] = description
+    if (authors.isNotEmpty()) metadata["authors"] = authors
+    if (createdAt != null) metadata["createdAt"] = createdAt
 
     val skillDocs = skills.values
         .sortedBy { it.name }
@@ -49,6 +62,9 @@ fun Agent<*, *>.toAgentJson(version: String? = null, description: String? = null
         "tools" to toolDocs,
         "capabilities" to linkedMapOf<String, Any?>("streaming" to true),
     )
+    if (locators.isNotEmpty()) {
+        spec["locators"] = locators.map { linkedMapOf<String, Any?>("type" to it.type, "urls" to it.urls) }
+    }
 
     val doc = linkedMapOf<String, Any?>(
         "apiVersion" to AGENT_JSON_API_VERSION,

src/main/kotlin/agents_engine/core/Skill.kt

@@ -191,6 +191,21 @@ class Skill<IN, OUT>(
         useMemory = true
     }
 
+    /**
+     * #4518 (PRD §12.6) — opt-in OASF taxonomy classification. [path] is the slash-delimited
+     * OASF skill path (e.g. `"agent_orchestration/multi_agent_planning"`); `toOasfRecord()`
+     * resolves it to the taxonomy uid via [agents_engine.agntcy.OasfTaxonomy]. Skills without
+     * an `.oasf(...)` are free-form and are omitted from the OASF record's `skills[]` (OASF
+     * skills are taxonomy entries, not free text) — with a validation warning.
+     */
+    var oasfPath: String? = null
+        private set
+
+    fun oasf(path: String) {
+        checkNotFrozen()
+        oasfPath = path
+    }
+
     fun execute(input: IN): OUT {
         val impl = checkNotNull(implementation) {
             "Skill \"$name\" has no implementation. Add implementedBy { } block."

src/main/resources/internals-agent/agntcy/OasfRecord.md

@@ -0,0 +1,63 @@
+---
+description: Source-file knowledge for agents_engine/agntcy/OasfRecord.kt + OasfTaxonomy.kt + OasfLocator.kt — OASF 1.0.0 record export (#4518, PRD §12.6), AGNTCY's content-addressed discovery metadata. Agent<*,*>.toOasfRecord(version, authors, locators, domains, description, createdAt, annotations) is the third discovery exporter beside A2A toAgentCard() and native agent.json. Skills become OASF skills[] only when annotated with .oasf("path"); the vendored OasfTaxonomy resolves path -> uid (lookup, not formula). Deterministic/byte-stable; createdAt/authors/locators caller-supplied (no hidden now()). Call when the IDE LLM reasons about exporting an agent into the AGNTCY directory.
+---
+
+# `agents_engine/agntcy/OasfRecord.kt` — OASF 1.0.0 record export (#4518)
+
+The **third discovery exporter** over the native typed agent, beside `A2AServer`/`toAgentCard()` (§12.5)
+and `toAgentJson()` (§12.2). AGNTCY's [OASF](https://github.com/agntcy/oasf) record is the discovery
+metadata that the DIR directory (a later subtask of epic #4517) stores content-addressed. The native
+agent stays the source of truth; this is a projection, exactly parallel to `toAgentCard()`.
+
+```kotlin
+val record: String = agent.toOasfRecord(
+    version = "1.2.0",
+    authors = listOf("Ada Lovelace <ada@example.com>"),
+    locators = listOf(OasfLocator("source_code", listOf("https://example.com/agent"))),
+    createdAt = "2026-06-15T00:00:00Z", // RFC3339, caller-supplied — see Determinism
+)
+```
+
+## Skills are taxonomy entries, not free text
+
+Only skills annotated with `.oasf("agent_orchestration/multi_agent_planning")` (the `Skill.oasf(path)`
+mutator, `core/Skill.kt`) become OASF `skills[]`. Each path resolves to its uid via `OasfTaxonomy`.
+Un-annotated skills — and annotated paths absent from the vendored taxonomy — are **omitted** with a
+`java.util.logging` warning (they remain in `agent.json`, which carries free-form skills). This is why
+an agent with no `.oasf(...)` annotations exports an empty `skills[]`.
+
+## OasfTaxonomy — vendored lookup, not a formula
+
+OASF uids are **explicitly assigned per node**: top-level categories are multiples of 100, but level-2
+is `category + n` while level-3 is `level2*100 + nn` — there is *no* single formula. So `OasfTaxonomy`
+is a `path -> uid` lookup loaded from `resources/oasf/skills-1.0.0.tsv` (+ `domains-1.0.0.tsv`).
+- **Slice 1 (#4518, this change):** seeds the confirmed core of the skills tree; domains TSV is unseeded
+  (records emit an empty `domains[]`).
+- **Slice 2 (follow-up in #4518):** vendor the complete `agntcy/oasf` skills+domains trees and add a
+  build-time cross-check against `schema.oasf.outshift.com/api/skills`.
+
+## Determinism
+
+Fixed key order; same inputs → byte-identical JSON (like `toAgentJson`). Wall-clock and authorship
+(`createdAt`, `authors`, `locators`) are **caller-supplied**, never sampled — no hidden `now()`, so the
+record is reproducible and CI-stable. Record key order: `name, version, schema_version, description?,
+authors, created_at?, skills, domains, locators, modules, annotations`.
+
+## Shared provenance with agent.json
+
+`toAgentJson(..., authors, createdAt, locators)` gained the same optional provenance fields (additive,
+omitted when not supplied → existing callers stay byte-identical): `metadata.authors`,
+`metadata.createdAt`, `spec.locators`. `OasfLocator` (its own file for the one-type-per-file guard,
+#3199) is the shared `{type, urls}` value.
+
+## Out of scope (deferred, PRD §12.6)
+
+Record **signing** (Sigstore/cosign over OCI) is external to the record JSON. OASF **import/validate**,
+the **DIR** gRPC client, and **Identity-verify** are the other subtasks of epic #4517.
+
+## Related files
+
+- `core/AgentJson.kt` — sibling exporter; shares the provenance fields and `OasfLocator`.
+- `a2a/A2AAgentCard.kt` — the structural sibling discovery exporter (`toAgentCard()`).
+- `core/Skill.kt` — `oasf(path)` annotation + `oasfPath`.
+- `resources/oasf/skills-1.0.0.tsv` — the vendored taxonomy.

src/main/resources/oasf/domains-1.0.0.tsv

@@ -0,0 +1,5 @@
+# OASF 1.0.0 domains taxonomy — vendored path -> uid (slash-delimited machine names).
+# Source: schema.oasf.outshift.com/api/domains (cross-check against github.com/agntcy/oasf).
+# Slice 1 (#4518) leaves this unseeded — toOasfRecord emits an empty domains[] until slice 2
+# vendors the complete domains tree. `.oasf(...)`-style domain annotations resolve here when present.
+# Format: <slash/path>\t<uid>   ('#' comments and blank lines ignored)