# Osysharp.Assignments — a piece of work somebody asked for, owned until its outcome is reached

> `Osysharp.Assignments` keeps a piece of work that somebody asked for: who asked, the outcome wanted, and what must be true for it to be done. It completes when its criteria are met, never because everything attached to it happens to have finished.

<!-- id: agent-kit-assignments · area: agent · stability: preview · html: https://osysharp.com/reference/agent/kit-assignments/ -->

> **You are here:** [Building with agents](https://osysharp.com/reference/agent/guide/) › [The kits](https://osysharp.com/reference/agent/guide-kits/) › Assignments

## Summary        {#summary}
`Osysharp.Assignments` keeps a piece of work that somebody asked for: who asked, the outcome wanted, and what must be true for it to be done. It completes when its criteria are met, never because everything attached to it happens to have finished.

Agent work, processes, requests to people and work handed to other systems are attached to it. Any of them can fail, be replaced or take a month; the assignment stays. It can be reopened and keeps everything it had.

|  |  |
|---|---|
| Package | `Osysharp.Assignments`, version 1.1.0 |
| You add it with | `use Osysharp.Assignments;` in the app's manifest. |
| It sits on | [[agent-kit-llm\|Llm]] |
| It also uses | `Identity`, `Ui` — parts of the platform's own library |
| Bridges that arrive when it meets another kit | [[agent-kit-assignments-agents\|Assignments.Agents]], [[agent-kit-assignments-work-queues\|Assignments.WorkQueues]], [[agent-kit-privacy-assignments\|Privacy.Assignments]] |
| Its own test app | A workshop that services other people's machines — `kits/assignments/tests` |

## Description    {#description}

### What do you get without writing anything?   {#free}
- "Why is it not moving?": waiting, blocked, overdue, stalled — worked out, not typed in.
- Progress told apart from activity: a reminder is not progress.
- What it has cost, against a budget of its own.
- A page for one assignment: criteria, where it stands, work attached, history.

### When do you need it?   {#when}
When the way to the outcome is not known in advance. See [[agent-guide-choosing#assignment-or-process]] and [A parcel that never came — a case owned until it is right, closed, and opened again](https://osysharp.com/reference/agent/story-delivery/).

### What does it expose?   {#exposes}
The tables below are generated from the kit itself, not written by hand: `osy kits Osysharp.Assignments --surface` lists each of
them with the code of the kit's own test app that uses it, and the tests that show it working.

**Settings** — one line in the app, each field with a default.

| You write | It says |
|---|---|
| `app.Assignments = new AssignmentsSetup { StalledAfter, MaxDepth }` | How this app uses assignments. |

**Policies you answer** — each is a question the kit asks your app: `policy Name => …;`

| Policy | The question | Until the app says otherwise |
|---|---|---|
| `ErasesAssignments` | Who may take a person off assignments and erase what an assignment says. | the kit's own default |
| `OpensAssignments` | Who may ask for work — open an assignment. | the kit's own default |
| `OverseesAssignments` | Who reads and acts on every assignment, whoever asked for it: a coordinator, a team lead. | the kit's own default |
| `AcceptsAssignmentExceptions` | Who may close an assignment with a criterion unmet, by accepting a written exception for it. | the kit's own default |

**Functions you call**, those its own tests show most first.

| Function | What it does | Tests that show it |
|---|---|---|
| `OpenAssignment(NewAssignment ask)` | Ask for a piece of work. | 51 |
| `RemoveParticipant(Assignment a, Principal person)` | Take somebody off an assignment. | 51 |
| `SetAssignmentOwner(Assignment a, Principal owner)` | Name who is accountable for it. | 51 |
| `MoveAssignmentDeadline(Assignment a, DateTime? dueAt, string why)` | Move the date the outcome is wanted by — recorded with the date it was, the date it is and why. | 51 |
| `SetAssignmentBudget(Assignment a, decimal? budget)` | The most it may spend on models, in US dollars. | 51 |
| `AddCriterion(Assignment a, string text, string key = …, Assignment? metWhen = …)` | Add a criterion to an open assignment — what else must be true for it to be done. | 51 |
| `ReopenAssignment(Assignment a, string why, List<AssignmentCriterion>? noLongerMet = …)` | Open a closed assignment again — the outcome did not hold. | 51 |
| `TakePersonOffAssignment(Assignment a, Principal person, string standIn, string why)` | Take a person off an assignment: they are no longer on it, it is no longer theirs — asked by, owned by, closed by, waited on — and every line they wrote, every criterion they settled, reads `Some… | 51 |
| `AnonymiseAssignment(Assignment a, AssignmentScrub how)` | Erase what an assignment says about the person it is about. | 51 |
| `LinkAssignments(Assignment from, Assignment to, LinkKind kind = …, string why = …)` | Link two assignments. | 51 |
| `AttachWork(Assignment a, WorkAttachment what)` | Attach a piece of work to an assignment — or answer the one already attached under the same key. | 51 |
| `UpdateWork(AssignmentWork work, WorkUpdate change)` | Change what a piece of work stands for, who the next step is with, or when it is wanted by. | 51 |
| `BlockWork(AssignmentWork work, string why)` | A piece of work cannot move: what it needs is not there. | 51 |
| `UnblockWork(AssignmentWork work, string how = …)` | What a piece of work was blocked on is there again. | 51 |
| `CloseWork(AssignmentWork work, WorkState state, string result = …)` | A piece of work ended: done, failed or cancelled, with what it produced in words. | 51 |
| `CountWorkCost(AssignmentWork work, long total, bool chargedAsSpent = …)` | Count what a piece of work has spent on models, in millionths of a US dollar — `total` is what it has spent in all, so counting the same figure twice counts it once. | 51 |
| `MeetCriterion(AssignmentCriterion criterion, string metBy, Guid? evidence = …, string evidenceType = …)` | A criterion is met — say by what. | 23 |
| `CompletionOf(Assignment a)` | Whether `a` can be completed now. | 21 |
| `ConditionsOf(Assignment a)` | The conditions of `a`, now. | 17 |
| `CompleteAssignment(Assignment a, string outcome, string limitations = …, string obligations = …)` | Complete an assignment. | 17 |
| `DependenciesOf(Assignment a)` | What `a` depends on. | 17 |
| `ActivityOf(Assignment a, int take = …)` | An assignment's activity, newest first. | 15 |
| `NoteActivity(Assignment a, ActivityKind kind, string what, string branch = …)` | Something happened that established nothing: a reminder went out, a call was tried again, a summary was written, somebody left a note. | 14 |
| `BranchesOf(Assignment a)` | The assignment's parallel branches, each with its own two clocks — so progress on one never hides another that has gone quiet. | 14 |
| `WorkOf(Assignment a, string key)` | The piece of work attached to `a` under `key`, or null. | 13 |
| `AssignmentScope(Assignment a)` | The scope an assignment's model calls are charged to — `assignment:8f1c…`. | 11 |
| `CostOf(Assignment a)` | What an assignment has cost: its own calls, the work attached to it, and the assignments opened under it. | 11 |
| `CancelAssignment(Assignment a, string why)` | Call an assignment off. | 7 |
| `SheetOf(Guid assignment, int activity = …)` | The sheet of one assignment, as whoever asks may read it. | 7 |
| `NoteProgress(Assignment a, string what, Guid reference, string referenceType, string branch = …)` | Something was established — and it points at what it rests on. | 5 |
| `AddParticipant(Assignment a, Principal person, ParticipantRole role = …)` | Put somebody on an assignment: an assignee who does the work, a contributor who adds to it, an observer who follows it. | 4 |
| `RecordDone(Assignment a, string key, string title, string result, Guid? subject = …, string subjectType = …)` | Record that something was done for an assignment, once, under `key` — the other half of `DoneFor`. | 4 |
| `DoneFor(Assignment a, string key)` | What was already done for an assignment under `key`, or null when it has not been — ask before doing something that must not happen twice, and record it in the same unit of work as the doing:  va… | 3 |
| `WhyNotMoving(Assignment a)` | Why an assignment is not moving, in one paragraph a person or a coordinator reads — every reason of every condition that holds. | 2 |
| `AcceptException(AssignmentCriterion criterion, string why)` | Accept an exception for a criterion that is not met — in writing, by somebody the app trusts with that (`AcceptsAssignmentExceptions`). | 2 |
| `FailAssignment(Assignment a, string why, string limitations = …)` | Close an assignment as failed: it could not be done. | 2 |
| `AssignmentsNeedingAttention()` | The open assignments that hold a condition — what somebody who oversees them, or is on them, looks at first. | 1 |
| `RequireRoomIn(Assignment a)` | Refuse (`AssignmentBudgetSpent`) when the assignment's budget is used up — what starts work on its account asks first. | 1 |
| `CriterionOf(Assignment a, string key)` | The criterion of `a` called `key`. | 1 |
| `DependentsOf(Assignment a)` | What depends on `a`. | 1 |
| `ProgressWork(AssignmentWork work, string what, Guid reference, string referenceType)` | A piece of work moved on: something was established on the way. | 1 |
| `NoteWorkActivity(AssignmentWork work, ActivityKind kind, string what)` | Something happened on a piece of work that established nothing — it was reminded, it was tried again. | 1 |

**Screens and components you mount** — each is one line in a page of yours.

| Component | What it draws |
|---|---|
| `AssignmentView(assignment, open)` | An assignment's page. |
| `AssignmentOutcome(sheet)` | The outcome wanted — and, once it is closed, how it ended. |
| `AssignmentCriteria(sheet)` | What done means: each criterion, whether it is met and by what, and how many are. |
| `AssignmentStanding(sheet)` | Where an open assignment stands: every reason it is blocked, overdue, stalled or waiting, and who the next step is with. |
| `AssignmentWorkList(sheet)` | The work attached to it: each piece with where it stands and what it cost. |
| `AssignmentLinks(sheet, open)` | The assignments it has to do with: the one it was opened under, the ones under it, what it depends on. |
| `AssignmentCostLine(sheet)` | What it has cost, against its budget when it has one. |
| `AssignmentPeople(sheet)` | Who is on it, and as what. |
| `AssignmentActions(sheet, onComplete, onReopen)` | What whoever is looking may do: complete it — with the reason beside the button while it cannot be — or, once it is closed and they are in charge, open it again. |
| `AssignmentHistory(sheet)` | Everything that happened, newest first. |
| `CriterionRow(c)` | One criterion: whether it has been established, and by what. |
| `ReasonRow(what, why, tone)` | One reason an assignment is not moving. |
| `WorkRow(w)` | One piece of attached work. |
| `ActivityRow(l)` | One line of what happened. |

**Slots you can fill** — a place on the kit's screens where your app, or another kit, adds a section.

| Slot | What goes there |
|---|---|
| `AssignmentPanel(Guid assignment)` | What another kit adds to an assignment's page — a panel under the assignment's own: its repository, its requests, whatever the kit keeps for it. |

**Events your app can hear** — `[On] void Heard(EventName e) { … }`

| Event | When |
|---|---|
| `AssignmentErased` | A person was taken off an assignment, or what it said was erased. |
| `AssignmentOpened` | Somebody asked for a piece of work. |
| `AssignmentCompleted` | An assignment reached its outcome: every criterion met — or, `ByException`, the rest excepted in writing. |
| `AssignmentCancelled` | An assignment was called off. |
| `AssignmentFailed` | An assignment could not be done. |
| `AssignmentReopened` | A closed assignment was opened again: its outcome did not hold. |
| `AssignmentCriterionMet` | One of an assignment's criteria was met. |
| `AssignmentCriterionReopened` | A criterion that had been settled is back in question. |
| `AssignmentExceptionAccepted` | Somebody accepted, in writing, that a criterion will not be met. |
| `AssignmentWorkClosed` | A piece of work attached to an assignment ended: done, failed or cancelled. |

**Records your app grants access to** — the kit writes them; `partial entity X { security { … } }` says who else reads them.

| Record | What it is |
|---|---|
| `AssignmentCriterion` | One thing that must be true for an assignment to be done — a sentence, and whether it has been established. |
| `AssignmentActivity` | One line of an assignment's activity: what happened, when, who did it — and whether it was progress. |
| `AssignmentParticipant` | Somebody on an assignment — a person, or an agent's own account. |
| `AssignmentWork` | One piece of work attached to an assignment — what the assignment is waiting on, or has had done for it. |

## What to read next   {#read-next}
- [Osysharp.Assignments.Agents — an agent's work, attached to the assignment it is for](https://osysharp.com/reference/agent/kit-assignments-agents/) — an agent's work, attached to the assignment it is for
- [Osysharp.WorkRepositories — what an assignment knows, kept as items](https://osysharp.com/reference/agent/kit-work-repositories/) — what an assignment knows, kept as items
- [A parcel that never came — a case owned until it is right, closed, and opened again](https://osysharp.com/reference/agent/story-delivery/) — a parcel that never came — a case owned until it is right, closed, and opened again

## Go deeper   {#see-also}
- [Assignments — a piece of work owned until its outcome is reached (Assignments kit)](https://osysharp.com/reference/agent/assignments/) — criteria, reopening, progress, what can be attached, cost