Skip to content

Commit 47dd9ea

Browse files
LevinGuyLevinGuy
committed
feat(docs): enhance documentation with compatibility details and contribution guidelines
1 parent d5e7ce3 commit 47dd9ea

9 files changed

Lines changed: 290 additions & 16 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Contributing to ASIF
2+
3+
Help test whether a session record contains enough information for another person, agent or runtime to understand the work and assess a handoff. Contributions can begin with a concrete use case, a small fixture or an implementation experiment.
4+
5+
Start with the [current compatibility matrix](docs/compatibility.md). The format is a proposal and the local tools cover a subset. A contribution should state which capability it improves and how someone else can check it.
6+
7+
## Share a use case
8+
9+
Open a [GitHub issue](https://github.com/OndagoAI/agent-session-interchange-format/issues/new) with:
10+
11+
- The source and destination, including relevant versions.
12+
- The next task the recipient should be able to perform.
13+
- Information that needs to survive: selected inputs, files, decisions, instructions, tools or unresolved operations.
14+
- A minimal sanitized example and the expected interpretation.
15+
- What is missing or ambiguous in the current format or implementation.
16+
17+
Use invented data if a source record cannot be shared, and label it synthetic. Do not include credentials or private transcripts in a public issue.
18+
19+
## Choose a starting contribution
20+
21+
| Contribution | A reviewable result |
22+
|---|---|
23+
| Clarify a confusing field | A concrete ambiguity, proposed wording and the affected object links |
24+
| Improve semantic coverage | A named normative requirement, a positive fixture and a rejection case where applicable |
25+
| Document an adapter mapping | A source field mapped to ASIF, with identity, coverage and loss handling explained |
26+
| Test an unfamiliar session type | A small non-coding or multi-agent example with honest context fidelity |
27+
| Supply independent evidence | A versioned implementation report with commands, input digests and supported/unsupported outcomes |
28+
29+
These are suggestions for small contributions, not assigned issues or claims that maintainers have accepted a design. Check [existing issues](https://github.com/OndagoAI/agent-session-interchange-format/issues) and the [gap list](GAPS.md) before proposing larger changes.
30+
31+
## Work on an adapter
32+
33+
Follow the [adapter-development guide](docs/adapters.md). Begin with an explicit source mapping and a narrow capability claim. Publish preservation limits before attempting native import or continuation.
34+
35+
The most useful integration evidence is a real session exported, assessed at a destination, continued under that destination's authorization and exported again. The [handoff evidence checklist](docs/adapters.md#the-first-live-handoff) describes what to retain. A local port of the reference implementation does not by itself establish independent interoperability.
36+
37+
## Prepare a pull request
38+
39+
Explain the problem, resulting behavior and affected ASIF/profile versions. Include reproducible commands and distinguish passed, failed and unsupported cases. For semantic changes, identify schema, documentation and fixture changes together.
40+
41+
Follow [getting started](docs/getting-started.md) to install the reference tools. Use checks relevant to the change:
42+
43+
```sh
44+
# Python examples and reference implementation
45+
.venv/bin/python tests/check_examples.py
46+
.venv/bin/python tests/check_reference.py
47+
48+
# TypeScript implementation
49+
npm run typecheck
50+
npm test
51+
52+
# Documentation (requires requirements-docs.txt)
53+
.venv/bin/python tests/check_documentation.py
54+
.venv/bin/python -m mkdocs build --strict
55+
```
56+
57+
Schema/profile changes also need the [structural and continuation checks](REFERENCE.md#reproducing-evidence-and-documentation). Regenerate object pages from their schemas and authored metadata with `docs/build_reference.py`; do not edit generated tables directly. Refresh the shared TypeScript parity corpus when continuation expectations change.
58+
59+
Keep discussion focused on reproducible behavior and treat contributors respectfully. The repository uses the [MIT license](LICENSE); the proposed [governance process](GOVERNANCE.md) and remaining contribution/release terms are documented separately. This guide does not establish a governing body or independent review roster.
60+
61+
## Open to independent implementations
62+
63+
ASIF began with the team behind Ondago. Implementers can use the format in their own applications, including competing products, without an Ondago account or runtime. Record actual implementation authorship and affiliation in [IMPLEMENTERS.md](IMPLEMENTERS.md) when submitting evidence; do not infer endorsements or independence from a project name.

‎README.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
# Agent Session Interchange Format (ASIF)
22

3-
**Carry an agent's work across computers, clouds, and providers. Let other agents join with the context they need.**
3+
**Your agent's work should be portable across tools, computers and clouds.**
4+
5+
Changing environments can mean manually rebuilding the brief, finding the right files and explaining decisions an agent already made. Another agent needs those details to make a useful next step.
46

57
ASIF is a proposed open format for agent sessions. It records the conversation together with selected model inputs, instructions, files, tool results, decisions and unfinished work. The goal is to make that work portable and understandable to another implementation, so people can change environments or bring in another agent without rebuilding the session by hand.
68

7-
[Documentation website](https://ondagoai.github.io/agent-session-interchange-format/) · [Getting started](docs/getting-started.md) · [Use cases](docs/use-cases.md) · [Specification](SPEC.md)
9+
[Documentation website](https://ondagoai.github.io/agent-session-interchange-format/) · [Try ASIF](docs/getting-started.md) · [Compatibility](docs/compatibility.md) · [Contribute](CONTRIBUTING.md) · [Specification](SPEC.md)
810

911
## Why ASIF?
1012

@@ -44,7 +46,15 @@ See the [use-case walkthroughs](docs/use-cases.md) for the handoff steps and wha
4446

4547
ASIF **0.3** is a session data-model proposal. This repository includes schemas, checked synthetic examples, and locally authored **Python and TypeScript CLIs** for validation, neutral request projection, selected file-tree restoration, packaging/signatures and redaction auditing.
4648

47-
The workflows above are integration goals. Real source/destination adapters, provider request encoding, live multi-agent coordination and independent interoperability evidence remain outstanding. ASIF describes shared session data; an application must implement agent scheduling, access control, synchronization and import. A valid session or a synthetic `ready` report does not establish that a destination can execute it. See [implementation scope](REFERENCE.md) and [remaining gaps](GAPS.md).
49+
The workflows above are integration goals. Real source/destination adapters, provider request encoding, live multi-agent coordination and independent interoperability evidence remain outstanding. ASIF describes shared session data; an application must implement agent scheduling, access control, synchronization and import. A valid session or a synthetic `ready` report does not establish that a destination can execute it. See the [compatibility and evidence matrix](docs/compatibility.md), [implementation scope](REFERENCE.md) and [remaining gaps](GAPS.md).
50+
51+
## Help test the handoff
52+
53+
If you build agents, coding tools, cloud runtimes or orchestration systems, bring a session that exposes a missing requirement. Useful contributions include a small sanitized example, a documented adapter limitation, or reproducible exchange results from an independent implementation. Start with the [contribution guide](CONTRIBUTING.md) or [adapter guide](docs/adapters.md).
54+
55+
The next integration milestone is a real source export, destination assessment, authorized next interaction and return export with recorded losses. It remains unproven; the [live-handoff checklist](docs/adapters.md#the-first-live-handoff) defines the evidence to collect.
56+
57+
The team behind Ondago started ASIF as a vendor-neutral proposal. You can implement it without an Ondago product or account. External implementers can contribute through this repository; the [governance charter](GOVERNANCE.md) remains proposed.
4858

4959
## Explore the format
5060

‎docs/adapters.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Building an ASIF adapter
2+
3+
An adapter maps a source session into ASIF or maps ASIF into a destination's representation. No vendor adapter is included in the local reference implementations. This guide is a starting workflow for experiments; the [specification](../SPEC.md), [semantics](../SEMANTICS.md) and activated profile rules define the contract.
4+
5+
## Start with a bounded export
6+
7+
Choose one source format and version, one complete example and a clear capture boundary. Describe the first claim you want to test, such as preserving conversation, participants and attachments for inspection. Native import and execution can be later capabilities.
8+
9+
| Source information | ASIF representation | Mapping question |
10+
|---|---|---|
11+
| Session and record identities | Session, capture and entity IDs | Can repeated exports preserve the same logical identities? |
12+
| Authors and messages | Participants and events | Are actor identity and message role both preserved? |
13+
| History selection | Branches and causal references | Which events belong to each selected history? |
14+
| Actual or proposed model inputs | Contexts with explicit fidelity | Do you know the ordered inputs, or only the visible transcript? |
15+
| Files and media | Resources and ordered content parts | Are original bytes present, transformed, redacted or unavailable? |
16+
| Tool activity | Tool definitions, calls and correlated results | Is a terminal outcome known? Is an earlier invocation outside this capture? |
17+
| Instructions and runtime needs | Configurations, environments and requirements | Which semantics are known, and which require a destination mapping? |
18+
| Outstanding work | Checkpoints, tasks and decisions | What is known at this boundary, and what remains unresolved? |
19+
20+
Keep a mapping record and account for unsupported or omitted data using coverage and losses. Preserve unknown optional data directly or through recoverable source data and a mapping receipt. Missing effective inputs must not become an `exact` context. See the existing [field mapping](field-mapping.md) for comparisons of source representations.
21+
22+
## Validate and inspect the export
23+
24+
Use either CLI against the produced document:
25+
26+
```sh
27+
node asif.ts validate /path/to/export.session.json
28+
# Substitute an actual context ID from your document:
29+
node asif.ts request /path/to/export.session.json CONTEXT_ID
30+
```
31+
32+
The request command supports a neutral projection of reconstructed or exact inputs within its stated limits. An unsupported result is useful evidence to record; it is not permission to drop those semantics. Check resource bytes and stable IDs across repeat exports, preserve separate identities for repeated messages, and test missing inputs and unresolved tool outcomes.
33+
34+
## Assess a destination
35+
36+
For a continuation claim, build the [portable-continuation profile](../CONTINUATION.md) and a separate destination report. Bind the report to the source bytes and selected plan. Assess workspace mapping, dependencies, tool behavior, configuration, services, model fit and unresolved operations for the actual destination.
37+
38+
Account for each adaptation and its acceptance. A destination needs its own authorization and access. Follow the profile's native-import, writer-coordination and rollback requirements for changes to a native store. An unresolved side effect needs reconciliation before a repeat action can be considered.
39+
40+
The [synthetic scenarios](../examples/continuation/README.md) explain the record structure. Their invented checks and historical timestamps cannot substitute for live destination observations.
41+
42+
## The first live handoff
43+
44+
Aim for one small, reproducible task and retain evidence at each stage:
45+
46+
1. **Capture:** record a real source session, source/runtime version, adapter revision and export boundary. Keep a shareable fixture or explain the reproducible sanitization.
47+
2. **Assess:** run destination checks and retain the report, explicit blockers, transformations and any required acceptance. Record destination versions and capability identity.
48+
3. **Import:** under destination authorization, perform the supported import and preserve its receipt and identity mappings. Record failures or rollback outcomes.
49+
4. **Continue:** demonstrate an actual next interaction that uses transferred information, such as answering a recorded unresolved question using a transferred file. Retain observed output and relevant tool results.
50+
5. **Return:** export the updated session, check preserved identities and resources, and account for lost or adapted state.
51+
6. **Reproduce:** publish the exact commands, revisions, fixture digests and outcomes so another developer can repeat the experiment without an Ondago product or account.
52+
53+
Keep a failed or blocked run as evidence of its actual outcome. Even a successful handoff between integrations with shared authorship does not satisfy the independent-implementation gate. Broader claims require additional sources, destinations, adverse cases and independent reports.
54+
55+
## Report the result
56+
57+
Use the [implementation evidence requirements](../IMPLEMENTERS.md) and link the report from a [GitHub issue](https://github.com/OndagoAI/agent-session-interchange-format/issues/new) or pull request. State read, interchange, context reconstruction and continuation results separately. The [compatibility matrix](compatibility.md) can then link to evidence for the exact scope demonstrated.

‎docs/compatibility.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Compatibility and evidence
2+
3+
ASIF **0.3** is a proposal with two locally authored reference implementations. This page separates executable checks, authored scenarios and integration work. It is not a list of certified providers. Both reference implementations share authorship; independent exchange evidence remains **zero**.
4+
5+
## Capability matrix
6+
7+
| Capability | Python reference | TypeScript reference | Evidence and limits |
8+
|---|---|---|---|
9+
| Parse and validate ASIF sessions | Implemented subset | Implemented subset | Structure and selected semantic invariants; [Python results](../tests/reference-results.json), [TypeScript results](../tests/typescript-results.json). Full semantic coverage remains open. |
10+
| Project a selected request context | Implemented | Implemented | Ordered typed inputs, resource references, tools and settings; no provider encoding or measured token budget. |
11+
| Exchange packages and signatures | Locally checked | Locally checked | [Bidirectional local checks](../tests/typescript-exchange-results.json); shared authorship, no independent interoperability claim. |
12+
| Restore selected plain file trees | Implemented subset | Implemented subset | Fresh destination only; Git administration, symlinks and native stores are unsupported. |
13+
| Assess continuation declarations | Implemented subset | Implemented subset | [Synthetic reports](../examples/continuation/README.md); no live capability, credential or account verification. |
14+
| Represent agents with different roles | Synthetic fixture checked | Synthetic fixture checked | [Shared-brief example](../examples/README.md#agents-with-different-roles); no real providers or live coordination. |
15+
| Export real native agent sessions | Not implemented | Not implemented | Requires a source adapter and stable identity mappings. |
16+
| Import into a native agent and continue | Not implemented | Not implemented | Requires a destination adapter, authorization and observed next-interaction evidence. |
17+
| Independent session exchange | Not demonstrated | Not demonstrated | Requires independently authored implementations and independently produced sessions. |
18+
19+
The [reference guide](../REFERENCE.md#typescript-differences-and-compatibility-evidence) describes numeric, archive and path-pattern differences. Successful validation establishes only the stated check scope.
20+
21+
## What a provider support claim needs
22+
23+
A named provider or runtime belongs in a compatibility report only after an implementer supplies reproducible evidence. Record source and destination versions, adapter revision, ASIF/profile versions, transferred fields, unsupported state and results for each direction. A successful export does not establish import or continuation support.
24+
25+
An adapter can start with a narrow claim such as readable conversation and resource export. If effective model inputs are unknown, label their fidelity accordingly. Expand the claim as additional capabilities are demonstrated. Use the [adapter guide](adapters.md) and [implementation evidence record](../IMPLEMENTERS.md).
26+
27+
## Next evidence milestones
28+
29+
1. Export a real source session with a documented mapping and a sanitized, reproducible fixture.
30+
2. Assess it for a named destination; make supported, adapted and blocked subjects explicit.
31+
3. Demonstrate an authorized next interaction and export its results back with stable identities and recorded losses.
32+
4. Have an independently authored implementation repeat the exchange with its own source session.
33+
34+
These are desired evidence milestones, not scheduled releases or completed work. [GAPS.md](../GAPS.md) tracks outstanding implementation and release requirements; [governance](../GOVERNANCE.md#maturity-levels) defines proposed maturity gates.

‎docs/getting-started.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,14 @@ ASIF describes an agent session as a portable JSON document. Start by validating
77
| Goal | Start with |
88
|---|---|
99
| See what ASIF is for | [Benefits and use cases](use-cases.md) |
10+
| Check demonstrated support | [Compatibility and evidence](compatibility.md) |
1011
| Understand the format | [Specification](../SPEC.md) and [session semantics](../SEMANTICS.md) |
1112
| Find a field or object | [Core object reference](objects.md) and [JSON schemas](schemas.md) |
1213
| Run local checks | [Reference CLI installation and commands](../REFERENCE.md) |
13-
| Build an adapter | [Field mapping](field-mapping.md), [conformance cases](../CONFORMANCE.md) and [implementation evidence](../IMPLEMENTERS.md) |
14+
| Build an adapter | [Adapter guide](adapters.md), [field mapping](field-mapping.md) and [conformance cases](../CONFORMANCE.md) |
1415
| Understand continuation | [Portable-continuation profile](../CONTINUATION.md) and [worked scenarios](../examples/continuation/README.md) |
1516
| Help close the remaining gaps | [Gaps and priorities](../GAPS.md) |
17+
| Share a use case or contribute | [Contribution guide](../CONTRIBUTING.md) |
1618

1719
## Run a first validation
1820

0 commit comments

Comments
 (0)